Referência da API
- Onde encontrar a documentação completa da API do AutoTalk
- Como autenticar requisições com sua chave de API
- Principais endpoints da API e o que eles fazem
O AutoTalk expõe uma API REST pública que permite a aplicações externas enviar mensagens para contatos e trabalhar com dados dinâmicos (Dynadata). A API segue a especificação OpenAPI 3.0.
Documentação interativa da API
A documentação completa e interativa da API está disponível em:
A partir dela, você pode navegar por todos os endpoints, ver schemas de requisição e resposta, e experimentar chamadas diretamente no navegador.
Autenticação
Toda requisição precisa carregar um dos três cabeçalhos. Todos os três resolvem para o mesmo contexto de empresa, compartilham os mesmos limites de uso (medidor mensal api_requests) e dão acesso aos mesmos endpoints — eles diferem apenas em como o token é emitido.
x-api-key (recomendado para integrações externas)
Uma chave de API de longa duração (formato sk-…) criada no painel do AutoTalk.
x-api-key: sk-YOUR_API_KEY
Para gerar uma, vá para Integrações > Tokens de API e clique no botão +. Veja Tokens de API para instruções passo a passo. Este é o cabeçalho que você quer usar para qualquer CRM, helpdesk, script ou ponte personalizada chamando o AutoTalk de fora.
x-jwt-token (uso interno dos assistentes do AutoTalk)
Um JWT de curta duração assinado pelo AutoTalk e emitido pela ação de workflow de assistente actions/security/auth/jwt/generate. O payload é {companyId, ips?, dur?}; a duração padrão é 300 segundos, opcionalmente restrita por uma lista de IPs permitidos validada contra o IP público real de quem chama, conforme visto pela borda do AutoTalk (cabeçalhos encaminhados como x-forwarded-for não são confiáveis).
x-jwt-token: YOUR_JWT_TOKEN
Os agentes usam isso para chamar /v1/ em nome da própria empresa — tipicamente a partir de uma etapa JavaScript (actions/code/javascript/execute) que recebe step(N).jwt como entrada. Não há endpoint público para gerar um; integradores externos devem usar x-api-key.
Um exemplo completo e funcional está em Discord Spam Moderator — um agente actor que gera um JWT e o utiliza para apagar spam do Discord, avisar infratores e expulsar reincidentes.
x-auth-token (cabeçalho unificado)
Um cabeçalho de conveniência que aceita qualquer das duas formas. Valores que começam com sk- são tratados como chaves de API; os demais são validados como JWT (e, se o valor for ambíguo, o JWT é tentado primeiro).
x-auth-token: sk-YOUR_API_KEY
# ou
x-auth-token: YOUR_JWT_TOKEN
Quando múltiplos cabeçalhos estão presentes, x-jwt-token vence x-api-key, e ambos vencem x-auth-token.
Trate os três tipos de token como senhas. Nunca os inclua em controle de versão nem os compartilhe em canais públicos. Se um token for comprometido, revogue-o (chaves de API) ou aguarde sua expiração (JWT) e rotacione.
URL Base
Todas as requisições de API usam a seguinte URL base:
https://api.autotalk.io/v1
Principais endpoints
Abaixo está uma visão geral das principais áreas da API. Para detalhes completos de requisição/resposta, visite a documentação interativa.
Empresa
| Método | Caminho | Descrição |
|---|---|---|
| GET | /v1/self | Recuperar o perfil da empresa autenticada |
Contatos
| Método | Caminho | Descrição |
|---|---|---|
| POST | /v1/contacts/{contactId}/send_message | Enviar uma mensagem para um contato específico |
Dynadata (dados dinâmicos)
Os endpoints Dynadata permitem gerenciar entidades de dados personalizadas (contatos, pedidos, tickets ou qualquer tipo que sua empresa defina).
| Método | Caminho | Descrição |
|---|---|---|
| GET | /v1/dynadata/types | Listar todos os tipos de Dynadata disponíveis |
| POST | /v1/dynadata/type/{type}/list | Listar itens de um tipo específico |
| GET | /v1/dynadata/type/{type}/item/{_id} | Recuperar um único item por ID |
| POST | /v1/dynadata/type/{type}/create | Criar um novo item |
| POST | /v1/dynadata/type/{type}/update | Atualizar um item existente |
| DELETE | /v1/dynadata/type/{type}/item/{_id} | Excluir um item por ID |
| POST | /v1/dynadata/type/{type}/validate | Validar um item sem salvar |
| GET | /v1/dynadata/type/{type}/schema | Obter o schema JSON de um tipo |
| GET | /v1/dynadata/type/{type}/schema/zod | Obter o schema Zod de um tipo |
| POST | /v1/dynadata/type/{type}/executeFunction/{functionName} | Executar uma função em um tipo |
| POST | /v1/dynadata/type/{type}/item/{_id}/executeFunction/{functionName} | Executar uma função em um item específico |
Armazenamento
Envie arquivos (imagens, PDFs, áudio) e obtenha uma referência primária {bucket, fullPath} que pode passar para send_message, campos de documentos Dynadata ou funções como createWhatsappWebEvoProduct. Veja Enviando arquivos.
| Método | Caminho | Descrição |
|---|---|---|
| POST | /v1/storage/upload-url | Reservar uma URL de upload assinada (etapa 1) |
| POST | /v1/storage/upload-complete | Finalizar o upload; retorna {bucket, fullPath} (etapa 2) |
| GET | /v1/storage/url | Obter uma URL de download de curta duração para um objeto armazenado |
Transcrições
A API de transcrição assíncrona independente (issue #822). Enfileire um job de transcrição para um arquivo de áudio armazenado e consulte seu status e resultado. Autenticada com seu x-api-key.
| Método | Caminho | Descrição |
|---|---|---|
| POST | /v1/transcriptions | Enfileirar um job de transcrição |
| GET | /v1/transcriptions/{id} | Obter o status e o resultado de um job |
Exemplo de requisição
Aqui está um exemplo de envio de uma mensagem de texto para um contato usando curl:
curl -X POST https://api.autotalk.io/v1/contacts/CONTACT_ID/send_message \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"body": {
"text": "Hello! How can we help you today?"
}
}'
Próximos passos
- Tokens de API -- Gere e gerencie suas chaves de API
- Webhooks -- Receba notificações de eventos do AutoTalk
- Workflows -- Automatize tarefas dentro do AutoTalk