Atualizado em Sep 17, 2026

Referência da API

O que você vai aprender

• 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:

https://api.autotalk.io/docs

A partir dela, você pode navegar pelos endpoints documentados, ver schemas de requisição e resposta, e experimentar chamadas diretamente no navegador. O documento publicado não cobre exatamente tudo o que está no ar: quando uma rota listada nesta página está de fora dele, esta página avisa nessa rota.

Autenticação

Toda requisição precisa carregar um dos três cabeçalhos — com uma exceção, o catálogo público de planos listado mais abaixo. 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 agentes do AutoTalk)

Um JWT de curta duração assinado pelo AutoTalk e emitido pela ação de workflow de agente actions/security/auth/jwt/generate. O payload é {companyId, ips?, dur?, scopes?}; 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).

Ative o modo avançado nessa ação para também pedir uma lista de scopes, e o token emitido fica limitado a essas capacidades no /v1 e no servidor MCP. Um token emitido sem lista de scopes não carrega a claim scopes e, portanto, não concede nada — ele autentica, mas todo gate o recusa, então sempre liste as capacidades de que suas etapas seguintes precisam. Uma lista de scopes fornecida com o modo avançado desligado é rejeitada (jwt_scopes_require_advanced) em vez de silenciosamente ignorada, e um nome de scope desconhecido é rejeitado na geração (jwt_invalid_scopes) em vez de descartado.

Todo token assinado pelo AutoTalk agora carrega uma claim kind que diz para que ele serve, e o /v1 aceita apenas kind: "v1" — um token emitido para outra finalidade (o redirecionamento de conexão de canal via OAuth, por exemplo) é rejeitado com 401. Os tokens são emitidos por execução e expiram em minutos, então não há nada a migrar. A exigência é incondicional: o /v1 recusa um JWT cuja claim kind esteja ausente, malformada (presente, mas não uma string utilizável) ou diferente de "v1", em toda requisição. Não há variável de ambiente nem etapa de implantação a executar pelo operador.

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 de código JavaScript (actions/code/execute com language: "javascript") 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.

dica

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

log_entries é somente leitura pela API

create, update e delete no tipo log_entries são recusados no /v1 e no servidor MCP para todos os chamadores — quaisquer que sejam as permissões que a chave de API tenha, e também para um x-jwt-token. A resposta é 403 com code: "log_entry_writes_not_allowed". O log_entries é a trilha de auditoria que a plataforma escreve sobre o seu tráfego de API, então nenhum scope concede a capacidade de forjar ou apagar linhas nele. As leituras (list, item, schema) não são afetadas.

Isso é uma mudança de comportamento: essas escritas funcionavam antes. Se você gravava registros próprios em log_entries, mova-os para um tipo de Dynadata seu (um custom type, por exemplo) — lá o create/update/delete continua igual. O exemplo publicado Discord Spam Moderator ainda contém chamadas desse tipo; elas agora falham, e o exemplo foi escrito de forma que um log falho não é fatal.

Operadores self-hosted podem definir V1_ALLOW_LOG_ENTRY_WRITES=true no backend para restaurar o comportamento antigo enquanto migram uma integração. O padrão é false e o ajuste não está disponível na plataforma hospedada.

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 assinada, válida por até 7 dias, 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

Transformações de mídia

A API assíncrona de transformação de mídia (issue #247). Enfileire uma conversão de formato para um arquivo de áudio ou vídeo armazenado e depois consulte o status e a saída. É a mesma fila de jobs usada pela ação de workflow Transformar Mídia e pela ferramenta MCP get_transcode_job, então um job enfileirado em qualquer superfície pode ser consultado pelas duas que fazem leitura: GET /v1/transcodes/{id} e a ferramenta get_transcode_job — a ação de workflow apenas enfileira, ela não lê. A sobreposição termina na leitura: cancelar e reexecutar existem apenas aqui, na /v1. O servidor MCP não registra nenhuma ferramenta de cancelamento nem de reexecução, e o documento do job é somente leitura para o tenant, então um job iniciado por um workflow ou pelo MCP pode ser cancelado ou reexecutado por estas duas rotas e por mais nenhuma.

Método	Caminho	Descrição
POST	/v1/transcodes	Enfileirar um job de transformação. fullPath e preset são obrigatórios; bucket é opcional e usa por padrão o bucket de storage da plataforma — um único bucket compartilhado por todos os tenants, com os arquivos da sua empresa sob um prefixo de caminho próprio — então raramente é preciso enviá-lo. Presets: mp4, ogg_opus, wav, flac_16k_mono
GET	/v1/transcodes/{id}	Obter um job. job.output.bucket e job.output.fullPath são o arquivo convertido, e só são preenchidos quando job.status for done
POST	/v1/transcodes/{id}/cancel	Cancelar um job que ainda não terminou — pending, probing, transcoding ou finalizing. Um job em qualquer outro estado é recusado
POST	/v1/transcodes/{id}/retry	Reexecutar do zero um job failed ou canceled. Qualquer outro status é recusado, assim como um job cujo lease de worker ainda esteja no futuro — todo caminho que escreve failed ou canceled limpa o lease, então essa segunda condição normalmente não deve atrapalhar, e as duas recusas voltam com o mesmo transcode_job_not_retryable. A requisição passa pelas mesmas verificações de cota de transcoding e de jobs na fila que o enfileiramento, e a conversão roda e é cobrada de novo a menos que essa mesma origem e predefinição já tenham sido convertidas, caso em que o resultado guardado é reaproveitado e nada é cobrado

Os presets, os limites de tamanho e duração, o teto de jobs por empresa e os códigos de falha são os mesmos aqui e na ação de workflow — veja Transformar Mídia.

Estes quatro ainda não estão na especificação interativa

O documento OpenAPI publicado por trás de api.autotalk.io/docs não lista os endpoints de transformação, então um cliente gerado a partir dele não os terá. As rotas estão no ar e são suportadas; esta tabela é a referência até a especificação alcançá-las.

Fala

Transforme texto em áudio armazenado, e antes disso reescreva o texto escrito na forma como ele seria falado. Nenhum dos dois endpoints devolve bytes de áudio: POST /v1/speech armazena o áudio e devolve uma referência {bucket, fullPath} que você pode passar direto para send_message, para um campo de arquivo do Dynadata ou para GET /v1/storage/url.

Método	Caminho	Descrição
POST	/v1/speech	Sintetizar text (no máximo 4096 caracteres) em um objeto de áudio armazenado. voiceProfileId e format são opcionais. Retorna a referência armazenada mais size, format e qual medidor foi cobrado
POST	/v1/spoken-text	Reescrever markdown (no máximo 8000 caracteres) na forma falada desse texto. Retorna apenas texto, sem áudio

POST /v1/speech é síncrono — o áudio já existe quando a chamada retorna e não há job para consultar. Markdown fica ruim quando lido em voz alta, então rode /v1/spoken-text antes quando o texto vier de um LLM ou de um campo de texto rico. A saída dele, porém, não é limitada em caracteres — apenas em tokens (1200 deles), o que normalmente fica bem abaixo do limite de 4096 caracteres da síntese, mas não é garantido, muito menos perto do máximo de 8000 caracteres de entrada. Confira o tamanho da reescrita antes de enviá-la para /v1/speech, e divida-a se tiver voltado maior.

Uso

Método	Caminho	Descrição
GET	/v1/usage	O snapshot de uso do tenant: totais dos medidores, tempo de compute separado por categoria, bytes usados de storage e de banco, o plano ativo com seus limites resolvidos e informações do período da assinatura

Aceita granularity=month (o padrão) ou granularity=day. A janela é um período de calendário em UTC — o mês atual, ou desde 00:00 UTC de hoje com granularity=day — o que não é necessariamente o período da sua assinatura. O snapshot em si é o mesmo que a ferramenta MCP get_usage retorna — as duas superfícies o leem do mesmo helper — mas os envelopes diferem: o MCP devolve o snapshot puro, enquanto a /v1 o embrulha como {success: true, usage}.

Workflows

Execute um workflow manual de forma direta (issue #218) e leia suas saídas duráveis — a returnExpression avaliada como result, arquivos de saída como refs de storage (utilizáveis com GET /v1/storage/url) e logs por etapa. Use mode: "async" para execuções longas (ex.: várias etapas de código Python) e consulte o endpoint do run; passe includeStepOutputs: true para também persistir snapshots por etapa.

Sempre verifique ok, não o status HTTP. Uma etapa que falha não aborta o workflow, então um run pode terminar com etapas quebradas: nesse caso a resposta é status: "partial" com ok: false, um error de código workflow_steps_failed e uma lista failedSteps: [{step, code, userMessage}]. Apenas status: "success" significa que o run fez o que devia.

Quando a falha faz parte do desenho — uma etapa cuja falha uma etapa posterior trata via step_error(N)/step_ok(N), ou um efeito colateral opcional — marque permitir falha nessa etapa no editor de workflows. A falha dela passa a ser reportada como {step, code, userMessage, handled: true}, exatamente como antes, mas não força mais status: "partial": um run cujas únicas falhas são tratadas continua status: "success", ok: true. Qualquer falha de etapa NÃO declarada assim ainda torna o run partial.

Método	Caminho	Descrição
POST	/v1/workflows/{id}/run	Executar um workflow (mode: "sync" retorna {ok, result, files, logs, executionTimeMs, runId}; mode: "async" retorna 202 {runId})
GET	/v1/workflows/{id}/runs/{runId}	Obter o status e as saídas duráveis de um run

Público (sem autenticação)

Método	Caminho	Descrição
GET	/v1/public/plans	O catálogo público de planos. Passe sellableOnly=true para retornar apenas os planos atualmente à venda

Este é o único endpoint desta página que não resolve nenhuma empresa e não exige cabeçalho de autenticação. Todo o resto precisa de um dos três cabeçalhos acima.

Assim como os endpoints de transformação acima, esta rota também não está no documento OpenAPI publicado, então um cliente gerado a partir dele não terá esta operação. A rota está no ar; a especificação é que ainda não alcançou.

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