API e webhooks do Call para desenvolvedores: chaves e eventos
Um tour prático pela API REST do Call: chaves de API e escopos, limites de requisições, tratamento de erros, webhooks assinados e a página Desenvolvedores.
Mais cedo ou mais tarde, um sistema de telefonia precisa conversar com outra coisa: um CRM que deve mostrar a chamada quando ela termina, uma ferramenta de cobrança que quer saber quem ligou, um script que faz uma ligação quando um formulário é enviado. O Call tem uma API REST e webhooks de saída exatamente para isso. Este guia explica como as peças se encaixam, o que pedir antes de escrever código e os erros que mais costumam custar uma tarde a um desenvolvedor.

Se o seu objetivo é só mover contatos em massa, leia antes Como importar contatos para o CRM da equipe de telefone; uma importação costuma ser mais fácil do que uma integração.
Por onde começar: a referência e a página Desenvolvedores
Há dois lugares que você precisa conhecer. A Referência da API fica em Configurações e também no menu Recursos da página inicial. Ela pode ser lida sem login, o que ajuda quando você está dimensionando um trabalho para um cliente. A página Desenvolvedores, também em Configurações, é para o seu próprio espaço de trabalho: ela mostra os identificadores da sua organização e do agente, seus endpoints de webhook e uma lista somente leitura das suas chaves.
O que cada lugar oferece
- Comece aquiURL base e convenções, autenticação com uma tabela de escopos e erros com códigos de status.
- EndpointsCada cartão de endpoint mostra o escopo, os parâmetros, o corpo da requisição, a resposta e os erros, com requisições prontas para copiar em curl, JavaScript e Python.
- PesquisarPressione / para ir à busca de endpoints e filtrar por método, caminho, escopo ou resumo.
- OpenAPI JSONBaixa a especificação completa em um único arquivo para as suas próprias ferramentas.
- ID do agente / APIO ID e o slug da sua organização, o modo da API (Sandbox ou Live) e o ID do agente de IA que você escolher, cada um com um botão Copiar.
- WebhooksSeus endpoints, os eventos que cada um recebe, o último status HTTP e as entregas que falharam.
Leia as seções sobre limites de requisições e webhooks de saída antes de entrar em produção, não depois. Elas descrevem comportamentos fáceis de passar despercebidos em um teste rápido.
Chaves de API e escopos
Toda requisição leva uma chave no cabeçalho Authorization, como bearer token. As chaves não são criadas no app: o operador do seu espaço de trabalho as emite e informa quais escopos elas têm. A chave completa aparece uma única vez, no momento da emissão, e depois só os primeiros caracteres ficam visíveis, então guarde-a imediatamente no seu cofre de segredos.
| Escopo | O que permite |
|---|---|
| read | Ler contatos, chamadas, filas, membros da equipe, relatórios e a lista de não ligar. |
| write | Criar e atualizar contatos, registrar resultados de chamadas e adicionar números à lista de não ligar. |
| calls | Fazer e encerrar chamadas. |
| admin | Gerenciar webhooks; também pode chamar todos os outros endpoints. |
Peça o menor conjunto que resolva o trabalho. Um script de relatórios precisa de read e mais nada; um botão de clique para ligar precisa de calls. Se uma requisição retornar 403 com o código insufficient_scope, falta à chave o escopo indicado no cartão daquele endpoint.
Sandbox e produção
As chaves podem ser emitidas para um sandbox, que usa um simulador e não faz chamadas reais, ou para uso em produção. Trate o prefixo de uma chave apenas como um rótulo: uma chave identificada como de teste funciona com os mesmos dados e a mesma conexão telefônica que uma de produção, então não conte com o prefixo para manter os experimentos longe dos clientes reais. Use o modo da API exibido na página Desenvolvedores para saber onde você está.
Como fazer chamadas pela API
Os endpoints públicos cobrem o básico: uma verificação de saúde, listar chamadas, ler uma chamada, fazer uma chamada, desligar, gerenciar webhooks e conversar com um agente de IA. Uma chamada ativa feita pela API passa pela mesma verificação de conformidade que uma chamada feita pela central, então um número na lista de não ligar ou fora do horário permitido é recusado, exatamente como seria para um atendente. Escreva seu código para tratar essa recusa como um resultado normal, não como um bug.
Isso importa para o design. Não escreva um loop que tenta de novo uma chamada recusada até ela funcionar. Leia o motivo, registre-o no log e siga em frente. Para as regras por trás dessas recusas, veja Proteção de horário de ligação no Call e A lista de não ligar no Call.
Limites de requisições e erros
Cada chave tem o próprio limite de requisições por minuto, definido na emissão; o padrão é 120. Quando uma chave esgota o minuto, a API responde 429 com o código rate_limited e informa quanto tempo esperar no cabeçalho X-RateLimit-Reset. Espere esse tempo e continue. Um cliente educado desacelera antes de bater no limite.
- 429 rate_limited: espere o período indicado no cabeçalho de reset e distribua o trabalho em massa ao longo do tempo.
- 403 insufficient_scope: falta à chave o escopo indicado no cartão daquele endpoint; peça uma chave com esse escopo.
- Outros erros: aja com base no código de erro, não na mensagem. Os códigos não mudam; o texto pode mudar.
Como tratar uma requisição que falhou
- Leia o statusÉ um erro do cliente que você pode corrigir ou um erro do servidor que vale a pena tentar de novo?
- Leia o códigoTome decisões pelo código, nunca pelo texto da mensagem.
- RecuePara 429, espere o tempo do cabeçalho de reset; para erros do servidor, tente de novo algumas vezes com intervalos crescentes.
- Registre os detalhesGuarde o endpoint, o código e o horário para que o suporte consiga rastrear.
- Pare nas recusasUma recusa de conformidade é uma decisão, não uma falha; não fique em loop tentando.
Webhooks: como receber eventos
Em vez de perguntar à API de novo e de novo se algo aconteceu, deixe que o Call avise você. Na página Desenvolvedores, clique em Adicionar endpoint, informe um endereço https público e marque os eventos desejados; não marcar nenhum significa todos os eventos. O segredo de assinatura aparece uma única vez, quando o endpoint é adicionado. Copie-o nesse momento. Se ele se perder, exclua o endpoint e adicione de novo para obter um novo segredo.
Cada entrega é assinada. O cabeçalho de assinatura traz um HMAC-SHA256 do timestamp e do corpo unidos por um ponto final, calculado com seu segredo de assinatura, e um cabeçalho separado traz o timestamp. Recalcule do seu lado e compare antes de confiar no conteúdo. A referência da API inclui código de exemplo para isso em Node.js e Python, e rejeitar timestamps antigos protege você contra requisições repetidas.
Um bom e um mau receptor de webhooks
| Bom | Ruim | |
|---|---|---|
| Assinatura | Verificada em toda requisição | Aceita sem conferir |
| Resposta | 2xx em segundos, com o trabalho enfileirado para depois | Processamento lento antes de responder |
| Duplicados | Recebe o mesmo evento duas vezes sem problemas | Cria dois registros |
| Falhas | Gera alertas quando as entregas falham | Fica em silêncio até alguém perceber |
Seu endpoint precisa responder com um status 2xx em até 10 segundos. Uma entrega que falha é tentada de novo, até seis tentativas no total, e um endpoint que falha 50 vezes seguidas é desativado. Cada linha da página Desenvolvedores mostra o último status HTTP e quantas entregas falharam, e Enviar teste dispara um evento de teste assinado para você ver o que seu servidor responde.
Checklist para entrar em produção
Antes de ativar uma integração
- Você sabe quais escopos a chave tem, e ela não tem mais do que o necessário
- A chave está guardada em um cofre de segredos, não no código-fonte
- As assinaturas dos webhooks são verificadas e timestamps antigos são rejeitados
- O receptor responde rápido e lida com eventos duplicados
- As respostas de limite de requisições e de recusa são tratadas sem loops de repetição apertados
- Você testou no modo sandbox e clicou em Enviar teste no endpoint
- Há uma pessoa definida para receber um alerta se as entregas começarem a falhar
Como fazer no Call
No Call, abra Configurações e depois Referência da API para estudar os endpoints, e Configurações e depois Desenvolvedores para copiar o ID da sua organização, conferir suas chaves e adicionar um webhook. Proprietários, administradores e gerentes podem adicionar, testar e excluir endpoints; as demais pessoas veem a lista. Se você também usa os recursos de agente de IA, o ID do agente na mesma página alimenta o endpoint de chat. Para o lado de voz do produto, veja Como configurar um agente de IA no Call.
Perguntas frequentes
Como consigo uma chave de API?
As chaves são emitidas pelo operador do seu espaço de trabalho; não podem ser criadas no app. Peça uma e diga quais escopos ela precisa ter. A chave completa aparece uma única vez, na emissão.
O que significa uma resposta 429?
A chave esgotou as requisições do minuto atual. Espere o número de segundos indicado no cabeçalho X-RateLimit-Reset, tente de novo e distribua o trabalho em massa por um período maior.
Como confiro se um webhook veio mesmo do Call?
Calcule um HMAC-SHA256 do timestamp e do corpo com seu segredo de assinatura e compare com o cabeçalho de assinatura. A referência da API mostra exemplos em Node.js e Python.
Posso enviar webhooks para um servidor de desenvolvimento local?
Não diretamente. Os endpoints precisam ser endereços https públicos, então use uma ferramenta de túnel que exponha seu servidor local em um desses endereços.
Por que minha chamada à API para fazer uma ligação foi recusada?
As chamadas feitas pela API passam pela mesma verificação de conformidade que as chamadas da central. Um número na lista de não ligar ou fora do horário permitido é recusado.
Quem pode ver e alterar os webhooks?
Todos podem ler a lista, mas só proprietários, administradores e gerentes podem adicionar, testar ou excluir endpoints.