Anil CRM
Conecte seu sistema ao Anil CRM: leia e crie contatos, acompanhe conversas, envie mensagens, aplique etiquetas, monte e ligue chatbots, converse com a sua equipe e receba eventos em tempo real por webhook.
https://api.anilcrm.com.br
O endereço antigo, https://api.msgflowapp.com.br, continua funcionando
para sempre — integração que já usa ele não precisa mudar nada. As mudanças desta
API ficam no histórico de mudanças, no fim da página.
404, como se não
existissem —, e campanha só sai pelos canais dela.
Mande a chave no cabeçalho Authorization, em toda requisição.
curl https://api.anilcrm.com.br/v1/me \
-H "Authorization: Bearer anil_live_xxxxxxxx_sua_chave_aqui"
A resposta confirma a credencial e mostra o alcance dela:
{
"tenantId": "...",
"tenant": { // a organização desta chave, por extenso
"id": "...",
"name": "Difafá Cosméticos",
"slug": "difafa-cosmeticos"
},
"key": { "id": "...", "name": "ERP produção", "prefix": "anil_live_xxxxxxxx" },
"scopes": ["contacts:read", "messages:send"],
"channelIds": [], // vazio = todos os canais
"owner": { "id": "...", "role": "ADMIN" }
}
Chame este endpoint primeiro, sempre. Ele é a resposta rápida para "por que deu 401?" e para "esta chave é da empresa certa?".
Se você administra mais de uma empresa, um risco real é usar a chave
de uma no ambiente de outra — e a requisição funcionar, agindo no lugar errado sem
nenhum sinal. Para fechar isso, mande junto o cabeçalho X-Anil-Org com o
slug da organização que você espera:
curl https://api.anilcrm.com.br/v1/me -H "Authorization: Bearer SUA_CHAVE" -H "X-Anil-Org: difafa-cosmeticos"
Se a chave for de outra empresa, a requisição para com 403 e a mensagem
diz quais são as duas. O slug sai do slug em /v1/me.
É opcional e compatível: integração que não manda o cabeçalho continua funcionando igual. Vale a pena quando o mesmo código roda contra empresas diferentes, ou entre ambientes de teste e produção.
Referer. A chave só é aceita no
cabeçalho Authorization.
/v1 é contrato; /api não é. O prefixo
/api é o backend da nossa própria tela e muda junto com ela, sem aviso.
Integre sempre por /v1.
O escopo diz o que a chave faz; o papel de quem a emitiu diz até onde
ela enxerga. Os dois se somam. Chamar uma rota sem o escopo dela devolve
403 nomeando o que falta.
| Grupo | Escopos |
|---|---|
| Contatos e etiquetas | contacts:read contacts:write labels:read labels:write labels:manage |
| Atendimento | conversations:read conversations:write messages:read messages:send |
| Campanhas, agenda e relatórios | campaigns:read campaigns:write reports:read scheduled:read |
| Funil de negócios | deals:read deals:write boards:write |
| Chatbots | chatbots:read chatbots:write |
| Mensagens da equipe (as suas) | team-messages:read team-messages:send |
| Organização (leitura) | sectors:read users:read channels:read quick-replies:read boards:read capture:read tracking:read |
| Base de conhecimento (IA) | knowledge:read knowledge:write |
labels:manage).
labels:write só aplica e remove. Criar mexe na lista de etiquetas da empresa
inteira e apagar tira a etiqueta de todo contato e conversa de uma vez — por isso fica
numa caixa separada. Configuração da organização é só leitura: criar
setor, usuário ou canal por API mudaria como a empresa atende, e um erro de
integração ali é muito pior que um contato errado. A exceção é o
chatbot: dá para montar e editar, mas ele nasce desligado e
ligar é uma chamada à parte.
| Rota | Escopo |
|---|---|
GET /v1/contacts | contacts:read |
GET /v1/contacts/:id | contacts:read |
POST /v1/contacts | contacts:write |
PATCH /v1/contacts/:id | contacts:write |
DELETE /v1/contacts/:id — excluir (as conversas ficam) | contacts:write |
GET /v1/contact-fields — campos personalizados que existem | contacts:read |
POST /v1/contacts/lookup — procurar até 100 telefones | contacts:read |
| Listagem — parâmetro | O que faz |
|---|---|
search | Parte do nome ou do telefone. |
labelId | Só quem tem esta etiqueta. |
ownerUserId | Só a carteira deste atendente; sem-dono = quem ainda não tem dono. |
origin | all (padrão), whatsapp ou instagram. |
sort | name_asc (padrão), name_desc, recent, oldest. |
page, limit | Página (desde 1) e itens por página — padrão 20, máximo 100. |
| Criar / editar — campo | O que é |
|---|---|
name | Obrigatório ao criar. |
phone | Obrigatório ao criar e não muda depois. Só dígitos, com DDI e DDD: 5517999998888. Telefone que já existe responde 409. |
email | Opcional; "" apaga. |
notes | As Notas do contato (até 10.000 caracteres). No PATCH substitui o texto inteiro. |
customFields | Campos personalizados, { "chave": valor }. No PATCH substitui o objeto inteiro — leia, mude e mande todos. |
optedOut | true = a pessoa pediu para não receber: sai de campanhas e automações. Só no PATCH. |
ownerUserId | Dono na carteira (id de /v1/users); null tira da carteira. |
| Rota | Escopo |
|---|---|
GET /v1/conversations | conversations:read |
GET /v1/conversations/:id — uma conversa | conversations:read |
GET /v1/conversations/:id/window — a janela de 24h está aberta? | conversations:read |
GET /v1/ai-agents — agentes de IA (para ligar numa conversa) | conversations:read |
POST /v1/conversations — abrir com um número | conversations:write |
POST /v1/conversations/:id/assign | conversations:write |
POST /v1/conversations/:id/unassign | conversations:write |
POST /v1/conversations/:id/resolve — finalizar (com venda ou perda, opcional) | conversations:write |
POST /v1/conversations/:id/reopen | conversations:write |
POST /v1/conversations/:id/transfer-sector | conversations:write |
POST /v1/conversations/:id/notes — nota interna | conversations:write |
POST /v1/conversations/:id/stop-chatbot — parar o chatbot nesta conversa | conversations:write |
PUT /v1/conversations/:id/ai-agent — ligar ou desligar a IA | conversations:write |
POST /v1/conversations/:id/read — marcar como lida | conversations:write |
| Ação | Corpo e efeito |
|---|---|
resolve | Sem corpo, só finaliza. Com { "outcome": { "result": "WON", "amountCents": 15000 } } registra a venda (valor em centavos), ou { "outcome": { "result": "LOST", "lossReason": "preço" } } a perda — entra no relatório de vendas e fecha o negócio aberto no funil, igual à tela. Corpo inválido: 400, e a conversa não é finalizada. |
stop-chatbot | O chatbot deixa de esperar a resposta e os lembretes dele são cancelados. Ele continua ligado para os outros clientes. |
ai-agent | { "aiAgentId": "…", "aiMode": "autopilot" } — a IA responde sozinha (Piloto); "copilot" — só sugere para a equipe; { "aiAgentId": null, "aiMode": null } desliga. Ligar gasta atendimento de IA da cota da organização: com a cota acabada, 409. Ligar com o cliente esperando faz a IA responder já. |
read | Zera o "não lida". ⚠ O cliente recebe o "visto" (tiques azuis) — é a mesma ação de abrir a conversa na tela. Responde 204. |
window | { insideWindow, restanteMs, kind, lastInboundAt, fepStartedAt }. insideWindow: true = dá para mandar texto livre agora; false no WhatsApp Oficial = só template. kind: service (atendimento aberto), fep (lead de anúncio: só template, mas grátis, até 7 dias) ou none. restanteMs = quanto falta para fechar. |
| Listagem — parâmetro | O que faz |
|---|---|
status | OPEN (na fila, aguardando), IN_PROGRESS (em atendimento) ou RESOLVED (finalizada). |
assignedTo | Só as de um atendente (id de /v1/users). |
channelId, labelId | Só de um canal / com uma etiqueta. |
dateFrom, dateTo | Data e hora com fuso (2026-10-01T00:00:00-03:00). |
unread | true = com mensagem não lida. |
unanswered | true = o cliente escreveu e nenhuma pessoa respondeu depois (robô, saudação e nota não contam). |
overdue | true = passaram do prazo dos timers de inatividade. |
isGroup, archived | true/false: só grupos ou só individuais; arquivadas. |
search, searchIn | Busca. searchIn: name, phone, messages (dentro do texto das conversas — a mais lenta) ou all (padrão). |
page, pageSize | Página (desde 1) e itens por página — padrão 20, máximo 100. Aqui é pageSize, não limit. |
Cada conversa aparece uma vez; na busca, matchTypes diz por
onde ela casou (name, phone, message) e
matchedMessage traz a mensagem que casou.
assign recebe { "userId": "..." }.
transfer-sector recebe { "sectorId": "..." }, ou
null para tirar do setor. Para desatribuir use
/unassign — não um null no assign.
notes grava uma nota interna na conversa — a equipe vê, o
cliente não recebe nada: { "content": "Combinado entrega na sexta" }. Com
"saveToContact": true, a nota vai também para as Notas do contato
(pede também o escopo contacts:write). Fica em nome do administrador dono da chave.
| Rota | Escopo |
|---|---|
GET /v1/conversations/:id/messages | messages:read |
POST /v1/conversations/:id/messages — texto | messages:send |
POST /v1/conversations/:id/messages/media — mídia | messages:send |
POST /v1/conversations/:id/messages/template — template | messages:send |
POST /v1/conversations/:id/messages/schedule — agendar | messages:send |
POST /v1/conversations/:id/messages/schedule-chatbot — agendar um chatbot | messages:send |
POST /v1/conversations/:id/messages/forward — reenviar uma mensagem que já existe | messages:send + messages:read |
POST /v1/conversations/:id/messages/location — localização | messages:send |
POST /v1/conversations/:id/messages/contact — cartão de contato | |
POST /v1/conversations/:id/messages/buttons — botões de resposta | |
POST /v1/conversations/:id/messages/list — lista de opções | |
POST /v1/conversations/:id/messages/link-button — botão com link | |
POST /v1/conversations/:id/messages/poll — enquete | |
POST /v1/messages/:id/react — reagir com emoji | messages:send |
POST /v1/messages/:id/transcribe — texto de um áudio | messages:read |
POST /v1/media/upload-url | messages:send |
GET /v1/messages/:id/download | messages:read |
Ler mensagens: vêm as mais recentes (pageSize: padrão 50,
máximo 100). Para as anteriores, mande before com o createdAt da
mais antiga que você já tem — é cursor, não página (page só vale junto com
search, que procura no texto da conversa).
Enviar texto aceita, além de content (até 4.096 caracteres):
quotedMessageId (responder citando uma mensagem), mentions
(em grupo: telefones só com dígitos, ou "all" para todos) e
signMessage: true (começa a mensagem com o nome do administrador dono da
chave, em negrito). Se a empresa obriga assinatura nas configurações, ela vai de
qualquer jeito.
/download devolve { url, fileName } — uma URL assinada e
temporária, não os bytes. Baixe a partir dela.
Na tela do Anil, toda mensagem enviada pela API aparece com o selo Via API · Nome (o administrador dono da chave) — a equipe sabe que foi a integração, e de quem. Mensagem que a sua automação manda direto pelo WhatsApp conectado (sem passar pela API do Anil) também aparece como Via API, e não como "Celular".
| Rota | Escopo |
|---|---|
GET /v1/labels | labels:read |
GET /v1/conversations/:id/labels | labels:read |
POST /v1/contacts/:id/labels/:labelId | labels:write |
DELETE /v1/contacts/:id/labels/:labelId | labels:write |
POST /v1/conversations/:id/labels/:labelId | labels:write |
DELETE /v1/conversations/:id/labels/:labelId | labels:write |
POST /v1/labels | labels:manage |
PATCH /v1/labels/:id | labels:manage |
DELETE /v1/labels/:id | labels:manage |
POST /v1/labels/sync-whatsapp | labels:manage |
Criar: { "name": "Lead quente", "color": "#22c55e" }. Sem
visibility, a empresa toda vê; "SECTOR" pede
sectorId, e "PRIVATE" fica só para o dono da chave. Nome repetido
responde 409. Editar muda só o que vier. Apagar responde 204 e
tira a etiqueta de todos os contatos e conversas — não tem desfazer.
sync-whatsapp recebe { "channelId": "…" } e traz as etiquetas do
WhatsApp Business daquele número (só o não oficial); devolve { "imported": 3 }.
| Rota | Escopo |
|---|---|
GET /v1/reports/overview | reports:read |
GET /v1/reports/team — cada atendente: conversas, tempos e resultado | |
GET /v1/reports/sources | |
GET /v1/reports/sales | |
GET /v1/reports/ai | |
GET /v1/reports/calls | |
GET /v1/reports/capture | |
GET /v1/reports/filters |
| Parâmetro | O que faz |
|---|---|
from, to | Período (AAAA-MM-DD ou data e hora). Sem eles, os últimos 7 dias. |
channelId / channelIds | Um canal, ou vários separados por vírgula. |
assignedTo / agentIds | Um atendente, ou vários. |
sectorIds | Setores; none = conversas sem setor. |
scope | individual (padrão, sem grupos), group (só grupos) ou all. |
timeMode | Como contar 1ª resposta, atribuição e resolução: business conta só o horário de atendimento de cada canal, sem feriados (igual à tela); wall conta o relógio corrido. Sem o parâmetro, a API usa wall — é o que ela sempre fez, e mudar quebraria quem já integra. |
/reports/filters devolve os canais, setores e atendentes disponíveis —
use para montar os filtros das outras rotas de relatório. Relatório é a rota mais pesada
da API: o limite é 30 por minuto. Chave presa a números: sem filtro de
canal, o relatório conta só os números dela; pedir um número de fora responde 404.
| Rota | Escopo |
|---|---|
GET /v1/sectors | sectors:read |
GET /v1/users | users:read |
GET /v1/channels | channels:read |
GET /v1/channels/:id/instagram-media — posts e Reels (?after= pagina) | channels:read |
GET /v1/channels/:id/templates — templates do número oficial | channels:read |
GET /v1/channels/:id/groups — os grupos do número (WhatsApp não oficial) | channels:read |
GET /v1/channels/:id/groups/:groupJid — um grupo: participantes, admins e link de convite | channels:read |
GET /v1/quick-replies | quick-replies:read |
GET /v1/boards — os funis | boards:read |
GET /v1/knowledge-bases | knowledge:read |
GET /v1/knowledge-bases/:id — a base e os documentos | knowledge:read |
POST /v1/knowledge-bases/:id/text — acrescentar texto | knowledge:write |
DELETE /v1/knowledge-bases/:id/documents/:documentId | |
GET /v1/capture-forms | capture:read |
GET /v1/capture-forms/:id/submissions — as respostas (?limit=, até 500) | capture:read |
GET /v1/tracking-links | tracking:read |
GET /v1/scheduled-messages | scheduled:read |
GET /v1/campaigns | campaigns:read |
GET /v1/campaigns/:id | campaigns:read |
GET /v1/campaigns/:id/recipients — quem recebeu, um a um | |
GET /v1/campaigns/:id/stats — os totais | |
POST /v1/campaigns/preview — quantos vai atingir | |
POST /v1/campaigns — criar | campaigns:write |
PATCH /v1/campaigns/:id — editar o rascunho | |
POST /v1/campaigns/:id/dispatch | |
POST /v1/campaigns/:id/pause | |
POST /v1/campaigns/:id/resume | |
POST /v1/campaigns/:id/cancel | |
GET /v1/me | nenhum |
A lista de campanhas aceita status (DRAFT, SCHEDULED,
RUNNING, PAUSED, COMPLETED, CANCELLED,
FAILED), q (parte do nome), page e
pageSize (padrão 20, máximo 100).
| Rota | Escopo |
|---|---|
GET /v1/chatbots | chatbots:read |
GET /v1/chatbots/:id — com o fluxo inteiro | chatbots:read |
GET /v1/chatbots/guide — formato do fluxo | nenhum |
POST /v1/chatbots/:id/simulate — testar sem enviar nada | chatbots:read |
POST /v1/chatbots — criar (nasce desligado) | chatbots:write |
PATCH /v1/chatbots/:id | |
POST /v1/chatbots/:id/activate — ligar | |
POST /v1/chatbots/:id/deactivate — desligar | |
DELETE /v1/chatbots/:id | |
POST /v1/conversations/:id/run-chatbot — rodar numa conversa | messages:send |
GET /v1/chatbot-folders — pastas, com quantos chatbots em cada | chatbots:read |
POST /v1/chatbot-folders — criar pasta | chatbots:write |
PATCH /v1/chatbot-folders/:folderId — renomear | |
DELETE /v1/chatbot-folders/:folderId — apagar (os chatbots vão para "Sem pasta") |
A listagem aceita search, status (DRAFT ou
PUBLISHED), isActive, folderId (uma pasta, ou
none para os sem pasta), page e limit.
Pastas organizam os chatbots na tela (um nível só, da empresa inteira) e
não mudam quem vê o chatbot nem quando ele dispara. Para pôr um chatbot numa pasta, mande
folderId ao criar ou no PATCH; "folderId": null tira
da pasta. Cada chatbot traz folder ({ id, name } ou
null).
| Rota | Escopo |
|---|---|
GET /v1/team/threads — as suas conversas (?unread=true) | team-messages:read |
GET /v1/team/threads/:threadId/messages | |
GET /v1/team/people — colegas | |
POST /v1/team/threads/:threadId/read — marcar como lida | |
POST /v1/team/threads/:threadId/messages | team-messages:send |
POST /v1/team/dm — abrir conversa com um colega |
Toda mensagem sai dentro de uma conversa. Se a pessoa já falou
com você, a conversa existe — pegue o id dela em
GET /v1/conversations e pule para o
envio.
Se ela nunca falou com você, abra a conversa primeiro:
curl -X POST https://api.anilcrm.com.br/v1/conversations \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"channelId": "uuid-do-canal",
"phone": "5517999998888",
"name": "Nadine"
}'
Responde 201 com a conversa. Use o id dela para enviar.
O channelId — ou seja, por qual número seu a conversa vai sair —
você pega em GET /v1/channels. O name é opcional e só
vale se o contato ainda não existir.
OPEN, "Aguardando") — enviar mensagem por ela também não atribui
ninguém. A que já existia continua com quem já atendia. Para dar dono, use
POST /v1/conversations/:id/assign.
curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-4821-confirmado" \
-d '{"content": "Seu pedido saiu para entrega!"}'
Para imagem, áudio ou documento veja enviar mídia.
Mesma ideia, com data e hora: a mensagem fica na Agenda do Anil e sai sozinha na hora marcada (com até 30 segundos de diferença). Texto ou template.
curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages/schedule \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lembrete-consulta-4821" \
-d '{
"content": "Oi, Nadine! Lembrete da sua consulta amanhã às 14h.",
"scheduledAt": "2026-10-08T09:00:00-03:00",
"cancelOnContactReply": true
}'
| Campo | O que faz |
|---|---|
scheduledAt | Data e hora com fuso (-03:00 para Brasília). Precisa estar no futuro. |
content | O texto. Use este ou template. |
template | { "templateName", "languageCode", "bodyParams" }, igual ao envio de template. Só canal Oficial. |
cancelOnContactReply | Não envia se o contato escrever antes da hora. |
cancelOnAgentReply | Não envia se alguém da equipe responder antes da hora. |
Responde 201 com a mensagem agendada. Para conferir a agenda, use
GET /v1/scheduled-messages?from=…&to=…&status=pending (escopo
scheduled:read; from e to também com fuso).
Para cancelar: DELETE /v1/scheduled-messages/:id (escopo messages:send) —
com ?group=true, cancela o agendamento inteiro (a mensagem e os lembretes
dela). Responde { "cancelled": n }; o que já saiu dá 409.
Agendar um chatbot (vários passos, mídia, botões):
POST /v1/conversations/:id/messages/schedule-chatbot com
{ "chatbotId", "scheduledAt", "cancelOnContactReply", "cancelOnAgentReply" }.
Na hora marcada o fluxo roda na conversa. O chatbot precisa estar publicado e ligado
(senão 400) e no alcance da chave. Cancela igual, pelo
DELETE /v1/scheduled-messages/:id.
São dois passos: você pede uma URL de upload, manda o arquivo direto para o storage, e depois envia a mensagem citando a chave que recebeu. O arquivo nunca passa pela API — por isso funciona com arquivo grande.
curl -X POST https://api.anilcrm.com.br/v1/media/upload-url \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"filename": "boleto.pdf", "contentType": "application/pdf"}'
# → { "uploadUrl": "https://...", "mediaKey": "...", "expiresInSec": 300 }
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: application/pdf" \
--data-binary @boleto.pdf
Use PUT, e o mesmo Content-Type que você informou no
passo 1. A URL vale 5 minutos.
curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages/media \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: boleto-4821" \
-d '{
"type": "DOCUMENT",
"mediaKey": "a-key-do-passo-1",
"fileName": "boleto.pdf",
"caption": "Segue o boleto"
}'
| type | Para quê |
|---|---|
IMAGE | foto, print, comprovante |
VIDEO | vídeo |
AUDIO | áudio |
DOCUMENT | PDF e afins — use fileName |
STICKER | figurinha (webp) |
A mediaKey tem que ser a que o passo 1 devolveu (ou de um arquivo que já está
no Anil): chave de arquivo de outra organização é recusada com 400 e
code: "MEDIA_OUTSIDE_TENANT". Também aceitos: quotedMessageId
e, em grupo, mentions — iguais aos do texto.
422, e não é necessária: lá não existe
janela de 24h.
No canal Oficial, se o contato não te responde há mais de 24 horas, mensagem
comum é recusada com 422. O único jeito de falar com ele é um
template aprovado pela Meta.
curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages/template \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"templateName": "confirmacao_pedido",
"languageCode": "pt_BR",
"bodyParams": ["Nadine", "4821"]
}'
bodyParams preenche {{1}}, {{2}}… na
ordem. O template precisa estar aprovado na Meta antes. Para ver os que existem, com
nome, idioma, status (só APPROVED envia) e o texto, use
GET /v1/channels/:id/templates — a lista vem da Meta na hora. Para saber se
precisa de template, GET /v1/conversations/:id/window.
Os mesmos tipos da tela, um caminho cada, todos em
POST /v1/conversations/:id/messages/<tipo> com o escopo
messages:send, Idempotency-Key e quotedMessageId
opcional. Respondem 201 com a mensagem.
| Tipo | Corpo |
|---|---|
location | { "lat": -20.27, "lng": -50.54, "name": "Loja", "address": "Rua A, 1" } (nome e endereço opcionais) |
contact | { "displayName": "Suporte", "phone": "5517999990000", "organization", "email", "url" } — o cartão que a pessoa salva com um toque |
buttons | { "bodyText": "Quer seguir?", "buttons": [{ "id": "sim", "title": "Sim" }], "footer", "header": { "type": "text", "text": "…" } } — 1 a 3 botões, título até 20 letras. O toque chega como mensagem (BUTTON_REPLY). |
list | { "bodyText", "buttonText": "Ver opções", "sections": [{ "title", "rows": [{ "rowId": "a", "title": "A", "description" }] }] } — até 10 opções no total, título até 24 letras |
link-button | { "bodyText", "displayText": "Abrir", "url": "https://…" } — um botão que abre o site |
poll | { "bodyText": "Qual cor?", "choices": ["Azul", "Rosa"], "selectableCount": 1 } — 2 a 12 opções; os votos chegam na conversa |
422 e nada sai. No não oficial, a aparência dos botões depende da versão do
WhatsApp de quem recebe. Nenhum destes aplica intervalo entre envios — o mesmo aviso do
envio de texto.
POST /v1/messages/:id/react com { "emoji": "👍" } reage (o cliente vê);
"" tira a reação. Responde 204.
POST /v1/messages/:id/transcribe devolve { "transcription", "cached" } de
um áudio (outro tipo: 422; áudio ainda baixando: 409). A
segunda chamada devolve o que já foi transcrito, sem custo.
curl -X POST https://api.anilcrm.com.br/v1/campaigns \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"name": "Promo de setembro",
"channelId": "uuid-do-canal",
"contentMode": "TEXT",
"messageText": "Oi {nome}! Temos novidade.",
"recipientSource": "SEGMENT",
"recipientIds": ["uuid-da-etiqueta"],
"minDelaySec": 30,
"maxDelaySec": 60,
"sendWeekdays": [1,2,3,4,5],
"sendHours": [9,10,11,14,15,16],
"dailyLimit": 200
}'
Ela nasce em DRAFT — criar não dispara. Confira e
então dispare:
curl -X POST https://api.anilcrm.com.br/v1/campaigns/ID/dispatch \
-H "Authorization: Bearer SUA_CHAVE"
| Ação | Quando vale |
|---|---|
POST /v1/campaigns/:id/dispatch | só em DRAFT |
POST /v1/campaigns/:id/pause | só em execução |
POST /v1/campaigns/:id/resume | só pausada |
POST /v1/campaigns/:id/cancel | enquanto não encerrou |
GET /v1/campaigns/:id | acompanhar o progresso |
GET /v1/campaigns/:id antes.
minDelaySec/maxDelaySec é o
intervalo aleatório entre mensagens (o padrão é 30–60s, e mais lento é mais
seguro). sendWeekdays usa 1=segunda. sendHours são as
horas cheias liberadas. sendChannelIds liga o rodízio entre vários
números.
segmentLabelIds, um campo que a API não lia — a campanha nascia sem ninguém.
O certo é recipientIds (na origem SEGMENT, os ids das
etiquetas). segmentLabelIds passou a ser aceito como sinônimo, então quem
copiou o exemplo antigo volta a funcionar sem mudar nada.
curl -X POST https://api.anilcrm.com.br/v1/campaigns/preview \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "campaignId": "ID", "recipientSource": "SEGMENT", "recipientIds": ["uuid-da-etiqueta"] }'
Devolve quantas pessoas a campanha atinge e quantas ficam de fora por terem pedido para
não receber — o mesmo recorte do disparo. Com campaignId, conta como o
disparo daquela campanha vai contar (o público de quem a criou).
PATCH /v1/campaigns/:id muda o rascunho (os mesmos campos de criar; só o que
vier muda). Depois de disparada, 409. Para acompanhar:
GET /v1/campaigns/:id/stats (enviadas, entregues, lidas, respondidas, falhas)
e GET /v1/campaigns/:id/recipients — pessoa a pessoa, com
status, responded=true|false, q (nome ou telefone),
page e pageSize (até 100).
Monte o fluxo do chatbot por API: o que ele pergunta, os botões, as condições, para qual setor ele passa a conversa. O desenho é o mesmo da tela — um chatbot criado aqui abre e edita normalmente no editor visual.
DRAFT e não responde
ninguém. Ligar é POST /v1/chatbots/:id/activate, numa chamada separada —
o mesmo cuidado da campanha, em que criar e disparar também
são duas chamadas. Toda resposta de chatbot traz ligado
(true só quando ele responde sozinho) e situacao por extenso.
isActive: true num rascunho não é ligado: só quer dizer que dá
para testá-lo numa conversa.
Um fluxo é uma lista de nós (os passos) e de fios (qual passo vem depois de qual). O guia completo, com todos os campos de cada nó, sai da própria API — é a mesma tabela que valida o que você manda:
curl https://api.anilcrm.com.br/v1/chatbots/guide \
-H "Authorization: Bearer SUA_CHAVE"
| Para | Nós — campo type | Saídas — campo sourceHandle |
|---|---|---|
| Começar | startTrigger — o gatilho | uma |
| Enviar | sendMessage, sendTemplate (Oficial), sendLocation, sendContact, sendPoll e sendCarousel (não oficial), replyComment (Instagram) | uma |
| Perguntar e esperar | askInput (resposta livre, com validação opcional: e-mail, telefone, CPF, número, data ou regex), askChoice (lista), buttons, followUp | askInput: uma — com validação, valid / invalid · askChoice: opt-0, opt-1… e noMatch · buttons: o id de cada botão e noResponse · followUp: responded / noResponse |
| Decidir | conditionData, conditionWeekday, conditionTime, randomSplit | true / false · randomSplit: A / B |
| Fazer | createNote, saveContactField, editLabels, statusWaiting, waitLimited, saveContact, openWhatsapp | uma · saveContact: saved / invalid · openWhatsapp: sent / failed |
| Encerrar | transferAgent, transferSector, endConversation, activateAiAgent, triggerFlow | nenhuma |
| Anotar o quadro | nota — post-it para a equipe; o chatbot ignora | nenhuma (não tem fio) |
Limites: até 200 nós e 500 fios. A validação por regex roda num motor de
tempo linear (RE2): não aceita lookaround ((?=…)) nem
retrorreferência (\1).
createNote grava uma nota interna na conversa — a equipe vê,
o cliente não. Com "saveToContact": true, a nota vai também para as
Notas do contato (fica na ficha e aparece em qualquer canal).
O gatilho fica no nó startTrigger, em
triggerType: manual (só roda quando alguém executa),
firstMessage (toda primeira mensagem de um contato novo),
keyword (mensagem que contém o termo), both,
windowExpiring, e no Instagram commentKeyword,
liveCommentKeyword e storyReply.
Para o commentKeyword valer só num post ou Reel, pegue o post em
GET /v1/channels/:id/instagram-media e preencha no gatilho:
mediaId (o id), mediaPermalink (o
permalink) e mediaCaption (a legenda, até 160
caracteres — a lista já devolve cortada). Sem mediaId, vale para
comentário em qualquer post.
curl -X POST https://api.anilcrm.com.br/v1/chatbots \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: bot-orcamento-v1" \
-d '{
"name": "Orçamento",
"channelId": "uuid-do-canal",
"flow": {
"nodes": [
{ "id": "inicio", "type": "startTrigger",
"data": { "triggerType": "keyword", "keyword": "orçamento, preço" } },
{ "id": "oi", "type": "sendMessage",
"data": { "message": "Oi, ${contact.firstName}! Já te ajudo." } },
{ "id": "menu", "type": "buttons",
"data": { "bodyText": "O que você procura?",
"buttons": [ { "id": "produto", "label": "Produtos" },
{ "id": "humano", "label": "Falar com alguém" } ] } },
{ "id": "catalogo", "type": "sendMessage",
"data": { "message": "Nosso catálogo: https://exemplo.com" } },
{ "id": "fila", "type": "transferSector", "data": { "sectorId": "uuid-do-setor" } }
],
"edges": [
{ "source": "inicio", "target": "oi" },
{ "source": "oi", "target": "menu" },
{ "source": "menu", "sourceHandle": "produto", "target": "catalogo" },
{ "source": "menu", "sourceHandle": "humano", "target": "fila" },
{ "source": "menu", "sourceHandle": "noResponse", "target": "fila" }
]
}
}'
Responde 201 com o chatbot e uma lista avisos — coisas que
não impedem, mas que você deveria saber (um termo curto demais no gatilho, um nó que
nunca é alcançado). A posição dos nós no editor é calculada sozinha; mande
position só se quiser escolher. Sem flow, o chatbot nasce
só com o gatilho manual.
400
com problemas:
{
"error": "Fluxo inválido (2 problemas): (1) nó \"oi\" (sendMessage): precisa de message ou media (2) …",
"problemas": [
"nó \"oi\" (sendMessage): precisa de message ou media",
"fio menu → fila [talvez]: sourceHandle \"talvez\" não existe; use: produto, humano, noResponse"
]
}
curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/run-chatbot \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"chatbotId": "ID_DO_CHATBOT"}'
Roda o fluxo agora, naquela conversa. Chatbot que nunca foi ligado roda o que você
gravou. Chatbot que já está no ar roda a versão publicada — para testar
as suas mudanças antes de publicar, mande "rascunho": true.
Responde {"status":"concluido"}, ou "aguardando_resposta"
quando o fluxo parou numa pergunta, junto com passos (o que ele fez).
Se o fluxo demorar (há pausa de até 5 minutos), a resposta é 202 com
"em_andamento" e ele segue sozinho. Chatbot desligado ou canal
desconectado: 409.
O escopo é messages:send: o efeito é mensagem chegando numa pessoa real.
Use uma conversa sua para testar.
curl -X POST https://api.anilcrm.com.br/v1/chatbots/ID/activate \
-H "Authorization: Bearer SUA_CHAVE"
# → { …, "status": "PUBLISHED", "isActive": true,
# "gatilhos": ["responde a qualquer mensagem que contenha: orçamento, preço"] }
Ligar publica o que está gravado e põe no ar. Antes, confere o fluxo
(ele pode ter sido mexido na tela) e recusa com 422 se houver problema.
gatilhos diz, em português, quando ele vai responder.
firstMessage responde a todo contato novo do canal — e só pode
haver um ligado por canal (o segundo dá 409). keyword casa
pedaço de palavra: oi dispara em boi e noite.
| Ação | Como funciona |
|---|---|
PATCH /v1/chatbots/:id | Troca name, description, visibility, sectorId, folderId e o flow inteiro — leia com GET /v1/chatbots/:id e mande de volta com a mudança. Num chatbot ligado, a mudança vai para o rascunho: os clientes continuam recebendo a versão no ar até você chamar /activate, que publica. Quem está no meio de um fluxo termina na versão em que começou. O canal não muda por API. |
POST /v1/chatbots/:id/deactivate | Para de disparar e cancela os follow-ups pendentes. O fluxo continua salvo. |
DELETE /v1/chatbots/:id | Apaga de vez — fluxo, versões e números. Não tem desfazer. Chatbot ligado precisa ser desligado antes; chatbot em uso por campanha, horário de atendimento, agendamento ou outro fluxo responde 409 dizendo onde. |
Dois nós fazem a ponte: o fluxo do Instagram pede o número, grava na lista de Contatos e chama a pessoa no WhatsApp pelo número que você escolher.
| Nó | O que faz |
|---|---|
saveContact | Grava o contato pelo telefone (phone, normalmente ${var:telefone}), com name e email opcionais. Quem já tem o número é atualizado; o lead do Instagram ganha o telefone no próprio contato. Sem DDI, assume Brasil. Sai por saved ou invalid (peça o número de novo). |
openWhatsapp | Abre a conversa no canal de WhatsApp escolhido (channelId) e envia a primeira mensagem em até 30 segundos: message no não oficial, template no Oficial. Opcional: sectorId da fila. Sai por sent ou failed. |
failed.
O exemplo completo — com a volta para pedir o número quando ele vem errado — está em
exemploInstagramParaWhatsapp, no guia.
curl -X POST https://api.anilcrm.com.br/v1/chatbots/ID/simulate \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "texto": "quero um orçamento" }'
O ensaio da tela: roda o rascunho no motor de verdade e devolve
saidas (o que o chatbot mandaria), caminho (os nós por onde passou),
tipoDoPasso e estado. Para a próxima mensagem do "cliente", mande
de volta o estado junto com o texto; sem estado, começa
do início. Nada sai para o WhatsApp e nada é gravado.
O funil da tela: etapas, negócios com valor e responsável, ganho e perda. Escopos
deals:read (ver) e deals:write (mexer) — chaves criadas antes de
18/10/2026 não os têm; crie uma chave nova com eles. A lista de funis é
GET /v1/boards (escopo boards:read). Criar, configurar e arquivar
o funil em si é boards:write (02/11/2026) — veja logo abaixo.
| Rota | Escopo |
|---|---|
GET /v1/boards/:id — o funil: etapas, totais e negócios abertos (?mine=true = só os do dono da chave) | deals:read |
GET /v1/boards/:id/people — quem enxerga o funil: só essas pessoas podem ser o ownerUserId de um negócio dele | |
GET /v1/deals/:id — um negócio, com o histórico | |
GET /v1/conversations/:id/deals — os negócios abertos do cliente da conversa (o desta conversa primeiro); ganho ou perdido sai da lista | |
POST /v1/boards/:id/deals — criar | deals:write |
PATCH /v1/deals/:id — editar | |
POST /v1/deals/:id/move — { "columnId" } | |
POST /v1/deals/:id/win — { "valueCents" } opcional | |
POST /v1/deals/:id/lose — { "lossReason", "lossNote" } | |
POST /v1/deals/:id/reopen | |
POST /v1/deals/:id/undo-ai — o "Desfazer" do movimento da IA (só enquanto ela foi a última a mexer; senão 409) |
| Criar / editar — campo | O que é |
|---|---|
contactId | Obrigatório ao criar. |
columnId | A etapa (de GET /v1/boards/:id). Sem ela, a primeira. |
conversationId | A conversa do negócio (opcional) — finalizar essa conversa com venda ou perda fecha o negócio junto. |
title, valueCents, ownerUserId, nextStep, nextStepAt, notes | O que se vende, o valor em centavos, o responsável (de /v1/boards/:id/people), o próximo passo (e quando, com fuso) e notas. No PATCH, null apaga. |
lossReason | preco, prazo, sem_resposta, concorrente, fora_perfil ou outro (com lossNote). |
409) — reabra antes.
404, e a lista de funis também filtra.
| Rota | Escopo |
|---|---|
GET /v1/boards/templates — os modelos (etapas prontas e a regra da IA de cada uma) | boards:read |
POST /v1/boards — criar | boards:write |
PATCH /v1/boards/:id — configurar (só o que vier muda) | |
DELETE /v1/boards/:id — arquivar |
curl -X POST https://api.anilcrm.com.br/v1/boards \
-H "Authorization: Bearer $ANIL_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Loja", "template": "loja", "channelIds": ["ID_DO_NUMERO"],
"captureNewLeads": true, "aiAutoMoveEnabled": true }'
| Campo | O que é |
|---|---|
name, template | Nome e o id do modelo. Obrigatórios ao criar. |
channelIds | Os números do funil (pelo menos um). Quem atende esses números passa a ver o funil. |
sectorId | Opcional: só quem é do setor vê. null no PATCH tira. |
captureNewLeads | Toda conversa nova desses números vira negócio na primeira etapa. Obrigatório ao criar. |
aiAutoMoveEnabled | A IA lê a conversa e muda o negócio de etapa sozinha (cada leitura gasta a cota de IA). Obrigatório ao criar. |
columns | As etapas, na ordem: [{ "id", "name", "color", "aiRule" }]. Ao criar, sem ela vêm as do modelo. |
columns no PATCH é a lista INTEIRA. Etapa com
id fica (e é renomeada), sem id nasce, e a que ficar de fora
sai — os negócios dela vão para a primeira etapa que fica (nunca somem).
Para renomear uma só, mande todas com os ids. Arquivar tira o funil da tela de todos, mas os
negócios e o histórico ficam (o relatório de vendas não perde nada). Com a chave presa a
números, o funil só pode usar números da chave.
O que o agente de IA consulta para responder: catálogo, preços, perguntas frequentes. Pela
API, você mantém a base em dia a partir do seu sistema. Escopos knowledge:read
(ver) e knowledge:write (acrescentar e tirar) — o segundo é novo (18/10/2026):
crie uma chave com ele.
curl -X POST https://api.anilcrm.com.br/v1/knowledge-bases/ID/text \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Idempotency-Key: precos-2026-10" \
-H "Content-Type: application/json" \
-d '{ "title": "Tabela de preços — outubro", "content": "Vestido azul: R$ 189…" }'
GET /v1/knowledge-bases/:id e tire o antigo com
DELETE /v1/knowledge-bases/:id/documents/:documentId. Até 50 mil caracteres
por texto.
As conversas internas da aba Mensagens → Equipe: o que os colegas escreveram para você, direto ou em grupo. Serve para o seu assistente (ou automação) ler o que chegou e responder por você.
404.
curl "https://api.anilcrm.com.br/v1/team/threads?unread=true" \
-H "Authorization: Bearer SUA_CHAVE"
Para ler uma conversa, use o id dela. Vêm as 30 mais recentes (até 100 com
pageSize), da mais antiga para a mais nova. Para as anteriores, mande
before com o nextBefore da resposta; nextBefore: null
quer dizer que acabou.
curl "https://api.anilcrm.com.br/v1/team/threads/THREAD_ID/messages?before=NEXT_BEFORE" \
-H "Authorization: Bearer SUA_CHAVE"
Responder (só texto; replyToId, opcional, cita uma mensagem):
curl -X POST https://api.anilcrm.com.br/v1/team/threads/THREAD_ID/messages \
-H "Authorization: Bearer SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"content": "Pode dar o desconto."}'
| O que acontece | |
|---|---|
| Ler pela API | Não marca como lida nem como entregue — quem mandou não vê diferença. Marcar é POST …/read. |
| Responder | Sai em seu nome, na hora, com notificação para o colega — sem marca de que veio da integração. E marca a conversa como lida. |
| Conversa nova | POST /v1/team/dm com o userId do colega (de /v1/team/people): abre ou devolve a que já existe. |
Fica de fora, de propósito: anexo, encaminhar, figurinha, criar grupo e as conversas com pessoas de outras empresas. Também não existe webhook dessas mensagens: o webhook é da empresa, e a conversa é sua.
Rede falha e bibliotecas HTTP repetem requisição sozinhas. Sem proteção, um retry de "enviar mensagem" vira mensagem duplicada no WhatsApp de uma pessoa real — dano visível e que não dá para desfazer.
Mande o cabeçalho Idempotency-Key com um valor único por operação
(o id do pedido no seu sistema serve bem). Repetir a mesma chave devolve o mesmo
resultado, sem executar de novo.
| Rota | Aceita |
|---|---|
POST /v1/conversations/:id/messages | sim |
POST /v1/conversations/:id/messages/media | sim |
POST /v1/conversations/:id/messages/template | sim |
POST /v1/conversations/:id/messages/schedule | sim |
POST /v1/conversations/:id/messages/schedule-chatbot | sim |
POST /v1/conversations/:id/messages/forward | sim |
POST /v1/conversations | sim |
POST /v1/campaigns | sim |
POST /v1/contacts | sim |
POST /v1/chatbots | sim |
POST /v1/conversations/:id/run-chatbot | sim |
POST /v1/conversations/:id/notes | sim |
POST /v1/team/threads/:threadId/messages | sim |
| Regra | |
|---|---|
| Quanto tempo vale | 24 horas. |
| O que conta como "a mesma" | A mesma chave de API, o mesmo método, o mesmo caminho (com os ids) e o mesmo valor de Idempotency-Key. O mesmo valor numa rota diferente, ou para outra conversa, executa normalmente. O corpo não entra na conta: não reaproveite o valor para outra operação na mesma rota. |
| O que fica guardado | Só resposta de sucesso (2xx). Deu erro (400, 404, 409, 422, 5xx)? A chave é liberada: corrija e repita com o mesmo valor. |
| Repetiu enquanto a primeira roda | 409 — espere e tente de novo, não troque o valor. |
O limite é por chave, não por IP — sua integração sai de um servidor só e não seria justo dividir balde com terceiros. Janela de 1 minuto, e cada rota tem o seu balde: estourar o envio não trava a leitura. Requisição sem chave (ou com chave malformada) conta pelo IP.
| Rota | Por minuto |
|---|---|
| Leitura (contatos, conversas, uma conversa, janela, mensagens, etiquetas, campos de contato, agentes de IA, organização, campanhas, destinatários e totais de campanha, respostas de captura, base de conhecimento, simular chatbot, chatbots, equipe, funil e negócios) | 120 |
/v1/me, guia de chatbot, filtros de relatório, link de download, posts do Instagram, templates | 60 |
| Escrita e exclusão de contato, procurar telefones, aplicar e remover etiqueta, pedir URL de upload, atribuir, devolver, finalizar, reabrir, transferir, nota interna, parar chatbot, IA na conversa, marcar como lida, cancelar agendamento, reagir, criar e mexer em negócio, marcar mensagem da equipe como lida | 60 |
Relatórios (overview, team, sources, sales, ai, calls, capture) | 30 |
| Editar campanha, prévia do público, acrescentar e tirar da base de conhecimento, grupos do número, criar, editar e apagar etiqueta, criar, configurar e arquivar funil | 30 |
| Importar etiquetas do WhatsApp | 10 |
| Envio e agendamento de mensagem (texto, mídia, template, reenviar, localização, contato, botões, lista, botão com link, enquete), agendar chatbot, transcrever | 30 |
| Abrir conversa | 30 |
| Campanhas: criar, disparar, pausar, retomar, cancelar | 30 |
| Chatbots e pastas: criar, editar, ligar, desligar, excluir, rodar numa conversa | 30 |
| Mensagens da equipe: responder e abrir conversa | 30 |
429. Toda resposta traz
x-ratelimit-limit, x-ratelimit-remaining e
x-ratelimit-reset (segundos até o balde encher de novo); o
429 traz também retry-after. Trate com espera progressiva.
As listas não têm todas o mesmo formato — confira a de cada rota. Datas vêm em ISO 8601
(UTC, com Z); as que você manda levam fuso (-03:00 para Brasília).
Telefone é sempre só dígitos, com DDI: 5517999998888.
| Rota | Resposta | Como andar |
|---|---|---|
| Contatos | { data, total, page, limit } | page + limit |
| Conversas, campanhas | { data, total } | page + pageSize |
| Chatbots | { items, total, page, limit } | page + limit |
| Mensagens de uma conversa | { data, total } | cursor: before = createdAt da mais antiga |
| Mensagens da equipe | { data, nextBefore } | cursor: before = nextBefore (null = acabou) |
| Posts do Instagram | { items, nextCursor } | cursor: after = nextCursor |
| Setores, equipe, canais, etiquetas, respostas rápidas, kanban, base, captura, links | lista simples [ … ] | vem tudo |
Ações sem nada a devolver (aplicar e remover etiqueta, apagar pasta) respondem
204, sem corpo. Criar responde 201.
Todo erro devolve JSON com error (a mensagem, em português, para gente ler).
Pode vir junto: details (no 400, o problema de cada campo),
problemas (no fluxo de chatbot) e code (um código fixo, para o
seu programa decidir sem ler a mensagem — a lista está abaixo).
| Código | O que significa |
|---|---|
400 | Corpo ou parâmetro inválido. Em fluxo de chatbot, vem junto problemas com tudo que corrigir. |
401 | Chave ausente, malformada, revogada, expirada — ou o dono dela foi desativado ou rebaixado, ou a organização foi fechada. Todos respondem igual, para não revelar qual prefixo existe. Reativar o usuário ou reabrir a organização religa a chave sozinho. |
403 | A chave é válida, mas (a) não tem o escopo da rota — a mensagem nomeia o que falta; ou (b) o X-Anil-Org enviado não é a organização da chave. |
404 | Não existe ou está fora dos canais da chave. Os dois casos respondem igual, de propósito: distinguir permitiria descobrir o que existe sem ter acesso. |
409 | Outra requisição com a mesma Idempotency-Key ainda está em andamento — ou o estado não permite a ação: canal desconectado (no envio), disparar campanha que já saiu, pausar o que não está rodando, retomar o que não está pausado, excluir chatbot ligado ou em uso, segundo chatbot de primeira mensagem no canal, rodar chatbot desligado, ligar a IA com a cota de IA acabada, cancelar agendamento que já saiu, mover negócio fechado, reabrir negócio aberto, editar campanha que já saiu do rascunho. |
422 | Pedido válido que não dá para cumprir: janela de 24h fechada no canal Oficial (use template), template em canal não oficial, contato sem telefone, disparar campanha sem destinatários, sem conteúdo ou com canal desconectado, ligar um chatbot cujo fluxo gravado tem problema. |
429 | Limite por minuto estourado. |
5xx | Erro nosso. A mensagem é genérica de propósito; tente de novo com espera, e com Idempotency-Key nas rotas que enviam. |
code | Quando |
|---|---|
MEDIA_OUTSIDE_TENANT | A mediaKey (ou o fileKey de um cabeçalho de template ou de uma mídia de campanha) não é um arquivo da sua organização. Suba o arquivo por POST /v1/media/upload-url e use a chave que ela devolver. |
A lista de code cresce aos poucos — trate um code que você não
conhece pelo status HTTP.
Em vez de ficar perguntando "tem novidade?", receba um POST assim que
algo acontece. Cadastre o endpoint em
Configurações → Webhooks (só dono ou administrador), escolha os eventos
e guarde o segredo que aparece na criação (começa com whsec_) — ele também
só é mostrado uma vez. A URL precisa ser https.
| Evento | Quando sai |
|---|---|
message.received | O cliente mandou mensagem (em conversa individual ou grupo). É o evento de maior volume — só assine se for tratar. |
message.sent | Saiu uma mensagem pelo Anil: atendente, IA, chatbot, campanha, agendada ou API. Mensagem que falhou não conta; agendada avisa quando sai, não quando é agendada. O que é digitado direto no WhatsApp do celular não entra. |
message.status | Uma mensagem que saiu foi entregue, lida, ouvida (áudio) ou falhou. Só avanço: um "entregue" que chega atrasado, depois do "lida", não gera evento. Volume alto — cada envio gera dois ou três. |
conversation.created | Abriu conversa com alguém: primeira mensagem de um número novo, pela tela, pela API, por comentário no Instagram, por página de captura ou pelo chatbot ("Chamar no WhatsApp"). Conversa aberta por campanha não avisa — são milhares de uma vez, e o message.sent de cada envio já conta a história. |
conversation.assigned | A conversa ficou com um atendente — pela tela, pela API, por um chatbot ou pela carteira do cliente. |
conversation.transferred | A conversa mudou de setor (e voltou para a fila dele, sem atendente). |
conversation.resolved | O atendimento foi finalizado. Traz o resultado comercial (venda ou perda) quando houve. |
capture.submitted | Alguém concluiu uma página de captura (formulário) — também quando não deixou telefone. |
deal.created · deal.moved · deal.won · deal.lost · deal.reopened | Um negócio do funil nasceu (tela, API ou captura), mudou de etapa (por gente ou pela IA do funil — byAi), foi ganho, perdido ou reaberto. Finalizar a conversa com venda ou perda também gera deal.won/deal.lost. |
contact.created | Entrou um contato novo, um por vez: pela tela, pela API, pela primeira mensagem de um número novo, por comentário no Instagram, por página de captura ou pelo chatbot. Reativar um contato excluído também conta. Não disparam: importação por planilha, agenda do celular, membros de grupo e sincronização de histórico — são lotes de milhares de uma vez. |
message.sent, conversation.assigned,
conversation.resolved e contact.created só passaram a sair em
17/10/2026. Antes disso a tela deixava assiná-los, mas só
message.received era entregue. Ver o histórico.
Um POST com Content-Type: application/json e este envelope — o
que muda de um evento para outro é o data:
{
"event": "message.received",
"timestamp": "2026-10-17T14:02:11.402Z",
"data": {
"conversationId": "…", "messageId": "…", "channelId": "…",
"type": "TEXT", "content": "Oi, ainda tem o vestido azul?",
"isGroup": false, "externalId": "…",
"contact": { "id": "…", "name": "Nadine", "phone": "5517999998888" }
}
}
| Evento | Campos de data |
|---|---|
message.received | conversationId, messageId, channelId, type, content, isGroup, externalId, contact (id, name, phone — null em grupo e no Instagram) |
message.sent | os mesmos de cima, mais hasMedia, sentAt, origin (atendente, ia, chatbot ou automatico — campanha, saudação), viaApi (true quando saiu pela API) e agent ({ id, name } de quem enviou, ou null) |
conversation.assigned | conversationId, channelId, status, isGroup, contact, assignedTo ({ id, name }), sector, previousAssigneeId, actorUserId (quem atribuiu; null = o sistema), viaApi, e reason: "carteira" quando foi a carteira do cliente |
message.status | messageId, conversationId, channelId, externalId, status (DELIVERED, READ, PLAYED ou FAILED), at e, na falha, errorCode e errorMessage (os do WhatsApp) |
conversation.created | conversationId, channelId, status, isGroup, contact, assignedTo, sector e origin: message, manual, api, instagram_comment, capture ou chatbot |
conversation.transferred | os mesmos da atribuição (o sector é o NOVO), mais fromSectorId e previousAssigneeId |
conversation.resolved | os mesmos da atribuição, mais outcome: { result: "WON" | "LOST", amountCents, lossReason } ou null |
capture.submitted | formId, formTitle, submissionId, contactId (null sem telefone), phone, name, email, endScreenId (o desfecho), answers ([{ questionId, question, fieldKey, value }], na ordem do formulário), utm e submittedAt |
deal.* | dealId, boardId, boardName, columnId, columnName, status, title, valueCents, ownerUserId, conversationId, contact, source, actorUserId, viaApi; em deal.moved, fromColumnId e byAi; em deal.lost, lossReason e lossNote; em ganho e perda, closedAt |
contact.created | contactId, name, phone, email, instagramId, createdAt e origin: manual, api, message, instagram_comment, capture ou chatbot |
O webhook avisa; o detalhe completo está na API. Com o conversationId ou o
contactId na mão, busque o resto em /v1. Campos novos podem
aparecer no data com o tempo — ignore o que você não conhece.
| Cabeçalho | O que é |
|---|---|
X-Anil-Signature | sha256= + o HMAC-SHA256 em hexadecimal (ver abaixo). |
X-Anil-Timestamp | Quando assinamos, em segundos desde 1970. |
X-Anil-Event | O evento (o mesmo do corpo). |
X-Anil-Delivery-Id | Id desta entrega. Uma retentativa chega com o mesmo id — use para não processar duas vezes. |
User-Agent | Anil-CRM-Webhook/1 |
Valide sempre — sem isso qualquer um que descubra sua URL pode postar
nela. A assinatura é o HMAC-SHA256, com o seu segredo, do texto
{X-Anil-Timestamp}.{corpo cru}:
// Node.js — use o corpo CRU (os bytes que chegaram), antes de qualquer parse
const crypto = require('node:crypto')
function webhookValido(corpoCru, cabecalhos, segredo) {
const ts = cabecalhos['x-anil-timestamp']
const recebida = cabecalhos['x-anil-signature'] || ''
// mais de 5 minutos: recuse (protege contra replay)
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
const esperada = 'sha256=' + crypto.createHmac('sha256', segredo)
.update(`${ts}.${corpoCru}`).digest('hex')
// tamanhos diferentes: o timingSafeEqual lançaria erro
if (recebida.length !== esperada.length) return false
return crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada))
}
Responda 2xx em até 15 segundos — processe depois, em fila
sua. Qualquer outra resposta (ou demora) é falha, e tentamos de novo:
5 tentativas no total, com esperas de 10 s, 20 s, 40 s e 80 s
(uns 2,5 minutos do primeiro ao último). A ordem de chegada não é garantida: use o
timestamp do corpo para ordenar.
Quando 10 eventos seguidos esgotam as 5 tentativas, o endpoint é desligado sozinho e o sino do Anil avisa o dono e os administradores. Uma entrega que dá certo zera a conta. Arrumou? Religue em Configurações → Webhooks. O histórico de cada entrega (status, tentativas e o começo da resposta do seu servidor) fica lá.
O Anil expõe um servidor MCP, o padrão que o Claude usa para falar com sistemas externos. Com ele você conversa com o CRM em linguagem natural: "quantas conversas estão na fila do setor de vendas?", "resume o atendimento do contato X".
No Claude, adicione um conector com:
https://mcp.anilcrm.com.br/mcp/sua-organização
Autentique com a mesma chave de API, no cabeçalho
Authorization: Bearer. A URL exata da sua organização aparece em
Configurações → Chaves de API, ao lado da chave — copie as duas do
mesmo lugar.
Os endereços antigos — /mcp sem a organização, e o domínio
mcp.msgflowapp.com.br — continuam funcionando para quem já tem um conector
configurado.
São 103 ferramentas: ler contatos, conversas, mensagens, relatórios, agendamentos e campanhas (contatos e conversas também por etiqueta); criar, editar e excluir contato (inclusive marcar que a pessoa não quer receber) e procurar vários telefones; aplicar e ver etiquetas, e criar, editar, apagar e importar do WhatsApp as etiquetas da organização; atribuir e finalizar atendimento (registrando venda ou perda); ver uma conversa e a janela de 24h; parar o chatbot; ligar ou desligar a IA numa conversa; marcar como lida; listar os templates do número oficial; cancelar agendamento; mandar localização, cartão de contato, botões, lista, botão com link e enquete; reagir; transcrever um áudio; ver o funil e criar, editar, mover, ganhar, perder e reabrir negócio (e desfazer o movimento da IA); criar, configurar e arquivar funil; editar campanha, ver quantos ela atinge, os destinatários e os totais; ler as respostas das páginas de captura; ver a base de conhecimento, acrescentar e tirar texto; simular um chatbot; ver os grupos do número; relatório por atendente; enviar mensagem, arquivo e template; agendar mensagem ou chatbot; reenviar uma mensagem para outra conversa; abrir conversa; criar, disparar, pausar ou cancelar campanha; escrever nota interna (e salvar nas Notas do contato); ler e responder as suas mensagens da equipe; listar os posts do Instagram; criar, renomear e apagar pastas de chatbot; e montar, editar, ligar, desligar, excluir e testar chatbot — peça em português ("cria um chatbot que pergunta o nome e passa para Vendas") e o assistente lê o guia do formato antes de montar.
campaigns:write na chave, o assistente pode disparar
campanha para milhares de pessoas. O disparo não tem desfazer. As
ferramentas que mudam alguma coisa (enviar, atribuir, etiquetar, editar, disparar…) são
marcadas para o Claude pedir sua confirmação antes de executar — só "marcar mensagem da
equipe como lida" e "preparar envio de arquivo" não pedem. Mas a decisão de dar esse
escopo ao MCP é sua: se não quiser, deixe a caixa desmarcada e ele continua podendo ler
e acompanhar campanhas.
chatbots:write na chave, o assistente pode ligar um chatbot
que responde sozinho aos seus clientes. Ligar também pede sua confirmação e
a resposta diz quando ele vai disparar — confira antes de aprovar. Sem esse escopo,
ele continua podendo ler os chatbots.
O /v1 só muda acrescentando: campo novo na resposta, rota nova, parâmetro
opcional novo. Quando um comportamento muda — mesmo para consertar —, ele aparece aqui.
| Data | O que mudou |
|---|---|
| 02/11/2026 |
Etiquetas: criar (POST /v1/labels), editar
(PATCH /v1/labels/:id), apagar (DELETE /v1/labels/:id) e importar as
do WhatsApp do número (POST /v1/labels/sync-whatsapp), com o escopo novo
labels:manage — labels:write continua só aplicando e removendo.
Etiqueta de setor recusa (400) setor de outra organização.Funil: criar ( POST /v1/boards), configurar
(PATCH /v1/boards/:id) e arquivar (DELETE /v1/boards/:id), com o
escopo novo boards:write; os modelos (GET /v1/boards/templates),
quem pode ser responsável (GET /v1/boards/:id/people), ?mine=true no
funil e o "Desfazer" da IA (POST /v1/deals/:id/undo-ai).Agendar chatbot: POST /v1/conversations/:id/messages/schedule-chatbot.
MCP: 103 ferramentas.
|
| 18/10/2026 |
Campanhas: editar o rascunho (PATCH), prévia do público,
destinatários e totais. Corrigido: o exemplo de criar mostrava
segmentLabelIds, que a API não lia — agora é recipientIds, e o nome
antigo é aceito como sinônimo.Base de conhecimento: ver a base, acrescentar texto e tirar documento (escopo novo knowledge:write).Também: respostas das páginas de captura, simular chatbot, grupos do número, relatório por atendente ( /v1/reports/team) e o webhook
capture.submitted.Chave presa a números: a lista de canais, os relatórios e a agenda de mensagens passaram a seguir os números da chave (antes mostravam a empresa inteira). Funil de negócios: escopos novos deals:read/deals:write;
ver o funil, ver/criar/editar/mover/ganhar/perder/reabrir negócio, os negócios da conversa;
webhooks deal.created, deal.moved, deal.won,
deal.lost, deal.reopened. GET /v1/boards passou a filtrar
pelos números da chave.Mensagens: localização, cartão de contato, botões, lista, botão com link e enquete ( …/messages/<tipo>); reagir e transcrever áudio. Webhook
message.status (entregue, lida, ouvida, falhou).Atendimento: GET /v1/conversations/:id e …/window
(janela de 24h); resolve aceita outcome (venda ou perda);
stop-chatbot; PUT …/ai-agent (ligar e desligar a IA, com a trava de
cota); …/read (marcar como lida); GET /v1/ai-agents.Templates: GET /v1/channels/:id/templates.Agenda: DELETE /v1/scheduled-messages/:id.Contatos: DELETE /v1/contacts/:id, GET /v1/contact-fields,
POST /v1/contacts/lookup.Webhooks novos: conversation.created e conversation.transferred.
MCP: 92 ferramentas.
|
| 17/10/2026 |
Webhooks: message.sent, conversation.assigned,
conversation.resolved e contact.created passaram a ser
entregues (antes, só message.received saía). message.received
ganhou contact.phone.Limite de uso: passou a contar por chave de fato — antes, por um defeito, contava pelo IP de quem chamava. Idempotência: o mesmo valor de Idempotency-Key em outra rota
(ou para outra conversa) executa; antes devolvia a resposta da primeira. Erro deixou
de ficar guardado.Lista de conversas com chave restrita a canal: a página vem cheia e o total certo (antes vinha curta).Arquivos: mediaKey/fileKey de outra organização
é recusado com 400 MEDIA_OUTSIDE_TENANT.Erros passaram a trazer code quando existe; erro interno
(5xx) não expõe mais a mensagem técnica.Endereço novo: api.anilcrm.com.br e mcp.anilcrm.com.br (os
antigos seguem). MCP: 54 ferramentas.
|
| 16/10/2026 | Template enviado pela API aparece no chat com o texto do template (antes, só o nome). |
| 15/10/2026 | Chatbot: editar grava o rascunho; o /activate publica. run-chatbot aceita "rascunho": true. Validação nas perguntas (askInput com valid/invalid) e o nó nota. |
| 13/10/2026 | Relatórios aceitam vários canais, atendentes e setores e o timeMode (sem ele, segue o relógio corrido). |
| 12/10/2026 | Mensagens da equipe (/v1/team/*); conversa aberta pela API nasce sem atendente; lista de conversas sem repetidas; posts do Instagram; pastas de chatbot; ligado/situacao nos chatbots. |
| 11/10/2026 | Nota interna (POST /v1/conversations/:id/notes). |
| 10/10/2026 | Chatbots pela API: criar, editar, ligar, desligar, excluir, rodar numa conversa e o guia. |
| 07/10/2026 | Agendar mensagem (…/messages/schedule). |