Como criar chaves de API e webhooks

Quem pode fazer: Proprietário, Administrador · Atualizado em 9 de outubro de 2026

A API pública deixa o seu sistema (um ERP, CRM ou site) enviar mensagens pela aidesk e consultar o status delas. Para isso, ele usa uma API key, uma chave secreta da sua organização. Os webhooks fazem o caminho contrário: a aidesk avisa o seu sistema quando uma mensagem é enviada, entregue, lida ou falha. Tudo isso fica em Configurações › Integrações › Geral.

Criar uma API key

Abra Configurações › Integrações › Geral.
No cartão Developer API, clique em Gerenciar.
Clique em Nova API key.
Preencha o Nome, de um jeito que identifique o sistema (por exemplo, "ERP Bella Moda").
Em Scopes, marque o que a chave pode fazer (veja abaixo).
Clique em Criar API key.
A chave completa aparece na janela API key criada. Clique em Copiar e guarde em um lugar seguro.

A chave começa com ak_live_ e só é mostrada uma vez. Depois, a lista mostra apenas o Prefixo, para você reconhecer qual é qual.

Scopes: o que cada chave pode fazer

messages:send: enviar mensagens.
messages:read: consultar o status de mensagens enviadas.
contacts:read, contacts:write e templates:read: vêm marcados por padrão.
webhooks:manage: cadastrar webhooks pela API. Não vem marcado por padrão.

Dê a cada sistema só os scopes de que ele precisa. Se uma chave tentar fazer algo fora dos scopes dela, a API recusa o pedido.

Usar a chave no seu sistema

A chave vai no cabeçalho de cada requisição, no formato Authorization: Bearer ak_live_... (ou no cabeçalho X-API-Key). Os endereços da API ficam em https://api.aideskbr.com/api/public/v1. Para testar se a chave funciona:

curl https://api.aideskbr.com/api/public/v1/ping -H "Authorization: Bearer ak_live_SUA_CHAVE"

Os detalhes técnicos de cada endpoint estão na documentação para desenvolvedores, em developers.aideskbr.com.

Guardar a chave com segurança

Trate a chave como uma senha: quem tem a chave envia mensagens em nome da sua empresa.
Guarde em um cofre de senhas ou nas variáveis de ambiente do servidor. Nunca publique em código aberto, planilhas ou mensagens.
Use uma chave por sistema. Assim, se uma vazar, você revoga só ela.
Se perder a chave, não é possível vê-la de novo: use Rotacionar para gerar outra.

Editar, rotacionar e revogar

Na lista de chaves, cada uma mostra Nome, Prefixo, Scopes, Status e a data de criação. As ações são:

Editar: muda o nome e os scopes. A chave continua a mesma.
Rotacionar: cria uma chave nova com o mesmo nome e scopes, e a antiga para de funcionar na hora. A nova aparece uma única vez na janela API key rotacionada. Atualize o sistema que usa a chave.
Revogar: desliga a chave de vez. Ela passa para o status Revogada e não autentica mais nenhuma requisição. Mensagens que já estavam na fila continuam sendo enviadas.

Webhooks: receber avisos das mensagens

Em Configurações › Integrações › Geral, no cartão Webhooks, clique em Gerenciar.
Clique em Novo webhook.
Preencha a URL do seu sistema que vai receber os avisos.
Marque os eventos: message.sent, message.delivered, message.read e message.failed.
Clique em Criar webhook.
Copie o Secret que aparece na janela Webhook criado. Ele também só é mostrado uma vez.

Cada aviso chega com uma assinatura HMAC feita com esse secret. Seu sistema usa o secret para conferir que o aviso veio mesmo da aidesk. Na lista, o status Saudável indica que a URL está respondendo, e Instável indica falhas na entrega dos avisos.

Outras integrações da tela

Formulários do Meta Ads: clique em Gerenciar e em Conectar páginas para receber os leads dos formulários de anúncios do Facebook e do Instagram. Depois, crie um workflow com o gatilho Meta Ads · Novo lead para salvar o lead, mandar um WhatsApp e o que mais precisar. Para parar de receber, use Desconectar na página.
Arbo - Superlógica: para imobiliárias. Na engrenagem Configurar APIs, informe os tokens das APIs de Imóveis e de Leads. Os imóveis e os leads aparecem nas abas Imóveis e Leads. Os leads sincronizam sozinhos a cada 5 minutos, e Sincronizar agora força uma atualização.

Quem pode fazer o quê

Proprietários e Administradores com permissão para gerenciar a API e os webhooks. Agentes não têm acesso a esta tela.

Problemas comuns

"Selecione ao menos um scope.": marque pelo menos uma permissão para a chave.
"Selecione ao menos um evento.": marque pelo menos um evento para o webhook.
"API key inválida": a chave foi digitada errada ou está incompleta. Confira se começa com ak_live_.
"API key revogada": a chave foi revogada ou rotacionada. Use a chave nova ou crie outra.
"API key ausente": a requisição chegou sem o cabeçalho Authorization ou X-API-Key.
"Scope ausente: …": a chave não tem a permissão necessária. Edite a chave e marque o scope indicado.
"Agentes não têm acesso às API keys": só Proprietários e Administradores gerenciam chaves.