API do SyncAtende
Para automações e agentes de IA falarem com os clientes pelo WhatsApp oficial, respeitando a fila e o atendimento humano.
Começando
Endereço base: https://app.syncatende.com.br/api/v1. Toda chamada leva a chave de API no cabeçalho, e o corpo vai em JSON UTF-8.
Authorization: Bearer syncatende_…
Content-Type: application/json; charset=utf-8
Onde criar a chave
No painel, o admin da empresa abre Equipe → Chaves de API e clica em Nova chave. Dá um nome que diga quem usa (por exemplo, "n8n atendimento"). Não há escolha de escopo: a chave dá acesso a toda a API, ou seja, ler, criar, alterar e excluir (listar e ler atendimentos, mensagens e mídia, enviar mensagem, marcar como lida, transferir ou concluir atendimento, notas, etiquetas, contatos e campos, cards do Kanban, webhooks e relatórios). A chave aparece uma única vez, com o botão Copiar; o SyncAtende guarda só o hash dela. Perdeu, revoga e cria outra.
A chave é da empresa, não de quem a criou: a automação continua funcionando quando esse admin sai. A lista mostra quem criou, quando, o último uso e quem revogou. Cada empresa pode ter até 20 chaves ativas.
Chaves de leitura criadas antes dessa mudança continuam só de leitura, e a lista as marca com o selo Somente leitura (antiga). Elas só aceitam GET; um POST, PUT, PATCH ou DELETE com uma delas recebe 403 antes de qualquer efeito. Para ter acesso total, crie uma chave nova e troque na automação.
Sem acesso ao painel, quem opera o servidor também cria pelo terminal. A chave também é de acesso total e fica registrada como criada pelo terminal (a opção antiga --leitura foi removida e, se vier, é ignorada):
bun .\pilot-apikey.ts criar "n8n atendimento"
bun .\pilot-apikey.ts listar
bun .\pilot-apikey.ts revogar <id>
Cada chave enxerga só os atendimentos da empresa dela. Chave ausente, errada ou revogada recebe 401, e revogar no painel corta a chave na hora.
Quando a automação fala
A API é feita para a automação e o humano não falarem por cima um do outro. Três regras valem para tudo que o cliente vê (enviar, reagir, marcar como lida):
| Regra | O que acontece |
|---|---|
| O atendimento está com um humano | Recusa com 409. Quando alguém clica em Iniciar no painel, a conversa passa a ser dele. |
| O atendimento foi concluído | Recusa com 409. |
| O cliente não escreve há mais de 24 horas | Recusa com 409 antes de chamar a Meta. Fora dessa janela a Meta só aceita mensagem-modelo aprovada, que ainda não existe na API. |
Na prática: a automação responde enquanto o atendimento está waiting e sem ninguém (assignedUserId: null). Todo aviso do webhook já traz essa resposta pronta em automation.canReply.
Descobrir os ids
Receita: como descobrir os ids de tudo o que a automação precisa, só com GET (basta uma chave de Leitura). Guarde os ids no fluxo em vez de digitar os nomes: o nome pode mudar, o id não.
| Preciso do id de… | Chamada | Onde vem |
|---|---|---|
| Setor (e qual é o padrão) | GET /sectors | sectors[].id, defaultSectorId |
| Pessoa da equipe | GET /agents | agents[].id, com setores e papel |
| Fase do Kanban | GET /kanban/stages (ou GET /kanban, que traz também o setor e a fase de encerramento) | stages[].id, nome, cor e ordem |
| Campo próprio do card | GET /kanban/fields | fields[].key (é a chave usada em fields do card) |
| Campo do contato | GET /contact-fields | fields[].key |
| Etiquetas | GET /tags | tags (do atendimento) e contactTags (do catálogo, com color); as do card são as do catálogo do contato |
| Card de um atendimento | GET /kanban/cards?ticketId=… | cards[0].id |
| Atendimento de um número | GET /tickets?phone=5511999990000 | tickets[].id |
Quem monta o fluxo uma vez e roda para sempre pode ler esses ids no começo da execução e usá-los nas chamadas seguintes. O contrato completo, com todos os formatos, está em GET /api/v1/openapi.json.
Atendimentos
/tickets?status=waitingLista os atendimentos, do atualizado mais recentemente para o mais antigo, uma página por vez. Todos os filtros são opcionais e se somam:
| Parâmetro | Filtra |
|---|---|
status | waiting (aguardando), active (com um humano) ou closed. |
sectorId, assignedUserId | Setor ou pessoa responsável. |
tag | Atendimentos com essa etiqueta. |
phone | Número do cliente, com ou sem o nono dígito. |
updatedSince | Mudou desde essa data (ISO 8601). Para sincronizar um CRM, guarde a hora da última leitura e peça só o que mudou. |
limit, offset | Tamanho da página (1 a 200, padrão 50) e quantos pular. hasMore: true diz que há outra página. |
{ "tickets": [ {
"id": "46260661-…", "customerName": "Lia Souza", "phone": "+5511997038002", "waId": "5511997038002",
"status": "waiting", "assignedUserId": null, "assignedName": null, "sectorId": null, "sectorName": null,
"unreadCount": 1, "lastMessage": { "text": "oii", "at": "2026-09-29T18:43:00.000Z", "from": "customer" },
"origin": "whatsapp", "createdAt": "…", "updatedAt": "…", "closedAt": null, "lastTransfer": null, "tags": [ "vip" ], "contactTags": [ "cliente-ativo" ]
} ], "limit": 50, "offset": 0, "hasMore": false }
Na empresa que atende pelo WhatsApp Web, sem API (origin: "web"), o atendimento pode ainda não ter número: phone vem null e aparece "phonePending": true. O campo só existe quando é true.
/tickets/{id}Um atendimento só, no mesmo formato: { "ticket": { … } }.
Ler mensagens
/tickets/{id}/messages?limit=50As últimas mensagens do atendimento, da mais antiga para a mais nova. limit vai de 1 a 200 (padrão 50).
{ "ticket": { … }, "messages": [ {
"id": "wamid.HBgN…", "direction": "inbound", "author": "customer", "type": "text", "text": "Quero ajuda",
"replyTo": null, "choice": null, "interactive": null, "media": null,
"status": "received", "statusAt": null, "error": null, "source": "cloud_api", "at": "2026-09-29T18:43:00.000Z"
} ] }
| Campo | Significado |
|---|---|
direction | inbound (do cliente) ou outbound (da empresa). |
type | text, image, audio, video, document, sticker, reaction, interactive, buttons, list, cta_url, entre outros. |
replyTo | Id da mensagem citada. Numa reação, a mensagem reagida. |
choice | A opção que o cliente tocou: { "id": "setor:financeiro", "title": "Financeiro" }. Vale para botão, lista e resposta rápida de mensagem-modelo. |
interactive | Nas mensagens enviadas com botões ou lista, o que foi oferecido. |
media | Arquivo da mensagem, com url para baixar. Veja Mídia. |
status | Das enviadas: accepted → sent → delivered → read (ou played, voz ouvida), ou failed. Só avança, mesmo que a Meta avise fora de ordem. |
error | Quando failed: { "code": 131047, "title": "…", "details": "…" }, o motivo que a Meta deu. |
source | cloud_api (pela API), echo (enviada pelo celular ou WhatsApp Web) ou history (sincronização). |
/messages/{id}Uma mensagem pelo id, com o status atual e o atendimento dela: { "message": { … }, "ticketId": "…" }. Serve para conferir se uma resposta foi entregue.
Enviar mensagens
/tickets/{id}/messagesUm só endpoint para todos os tipos. Sem type, é texto. Todos aceitam replyTo para citar uma mensagem da mesma conversa.
{ "text": "Olá! Seu pedido saiu hoje." }
{ "text": "Sobre isso: já resolvemos", "replyTo": "wamid.…" }
{ "type": "reaction", "messageId": "wamid.…", "emoji": "👍" }
{ "type": "reaction", "messageId": "wamid.…", "emoji": "" }
Texto até 4096 caracteres. Reação só vale para mensagens de até 30 dias; emoji vazio tira a reação. Resposta 201:
{ "message": { "id": "wamid.…", "direction": "outbound", "status": "accepted", … }, "ticket": { … } }
Repetir sem enviar duas vezes
Se a chamada demorar e o seu fluxo tentar de novo, mande o mesmo cabeçalho Idempotency-Key nas duas tentativas. A segunda devolve a resposta da primeira, com o cabeçalho Idempotent-Replayed: true, e o cliente não recebe a mensagem duas vezes.
Idempotency-Key: pedido-123-resposta-1
Use um valor único por mensagem que você quer enviar (até 200 caracteres), como o deliveryId do aviso somado a um contador. A chave vale por 24 horas e serve para qualquer POST da API. Se o pedido for recusado, a chave fica livre para a próxima tentativa. A mesma chave numa rota diferente recebe 422.
400 em vez de mandar "Ol�" ao cliente.Mídia
Enviar
O arquivo vai em base64 (o SyncAtende sobe para a Meta e guarda uma cópia) ou por link https público (a Meta baixa).
{ "type": "image", "caption": "Seu boleto", "media": { "data": "<base64>", "mime": "image/jpeg" } }
{ "type": "document", "media": { "url": "https://…/boleto.pdf", "filename": "boleto.pdf" } }
{ "type": "audio", "media": { "data": "<base64>", "mime": "audio/ogg", "voice": true } }
| type | Formatos | Tamanho | Legenda |
|---|---|---|---|
| JPEG, PNG | image | 5 MB | sim |
| MP4, 3GPP | video | 16 MB | sim |
| AAC, AMR, MP3, M4A, OGG | audio | 16 MB | não |
| qualquer | document | 100 MB | sim, e filename |
| WebP | sticker | 500 KB | não |
Legenda até 1024 caracteres. voice: true manda como mensagem de voz, com botão de play; precisa ser OGG/Opus mono. Formato ou tamanho fora da regra é recusado com 400 antes de subir.
O corpo de cada chamada vai até 24 MB; acima disso a resposta é 413. Base64 aumenta o arquivo em um terço, então isso cobre vídeo e áudio de 16 MB. Documento maior que uns 17 MB vai por media.url.
Baixar
/messages/{id}/mediaDevolve o arquivo, com a mesma chave. A mídia que o cliente manda é baixada da Meta assim que chega, porque lá ela só fica 7 dias. Em media.available a mensagem diz se o arquivo já está pronto; se a Meta não entregou, media.error diz por quê.
Botões e listas
{ "type": "buttons", "header": "Atendimento", "text": "Sobre o que você quer falar?", "footer": "Escolha uma opção",
"buttons": [ { "id": "setor:financeiro", "title": "Financeiro" },
{ "id": "setor:suporte", "title": "Suporte" },
{ "id": "humano", "title": "Falar com alguém" } ] }
{ "type": "list", "text": "Qual o assunto?", "button": "Ver opções",
"sections": [ { "title": "Pedidos", "rows": [
{ "id": "pedido:status", "title": "Onde está meu pedido", "description": "Rastreio da entrega" },
{ "id": "pedido:troca", "title": "Troca ou devolução" } ] } ] }
{ "type": "cta_url", "text": "Acompanhe seu pedido", "label": "Rastrear", "url": "https://…" }
| type | Limites |
|---|---|
buttons | 1 a 3 botões; title até 20, id até 256; text até 1024. |
list | button até 20; 1 a 10 seções e no máximo 10 opções somando todas; com mais de uma seção, cada uma precisa de title (até 24); opção: title até 24, description até 72, id até 200. |
cta_url | label até 20; url https; text até 1024. |
| todos | header e footer opcionais, até 60. Ids sem repetição. |
Quando o cliente toca, a mensagem dele chega com choice.id igual ao id que você definiu. Decida pelo id, não pelo texto.
Templates (fora das 24 horas)
Passadas 24 horas da última mensagem do cliente, só um template aprovado pela Meta chega a ele. A Central de disparo do SyncAtende cria o template, acompanha a aprovação ao vivo e envia. Estas rotas só respondem com a Central liberada para a empresa pelo provedor; sem isso, 403 com reason: broadcast_off.
/templatesLista os templates com status (APPROVED, PENDING, REJECTED, PAUSED…), statusLabel em português, quality, canSend e, quando rejeitado, reject.text com o motivo. Filtros status, category e q. O status muda sozinho: a Meta avisa a aprovação, a rejeição e a pausa por webhook, e o sistema ainda lê a conta da Meta a cada hora.
/templatesCria o template e manda para a análise da Meta (que costuma levar até 24 horas). O texto é conferido antes: se quebrar uma regra, a resposta é 422 com a lista errors (field, code, message). Variáveis têm nome, como {{nome}}, e cada uma precisa de um exemplo. Marketing leva por padrão o botão "Parar de receber"; "stopButton": false tira.
{ "title": "Aviso de promoção", "category": "MARKETING",
"body": { "text": "Olá {{nome}}, a promoção de outubro começa amanhã na loja do centro. Passe lá!", "examples": { "nome": "Maria" } },
"footer": "Loja Exemplo",
"buttons": [ { "type": "URL", "text": "Ver ofertas", "url": "https://exemplo.com.br/ofertas" } ] }
Cabeçalho de imagem, vídeo ou PDF leva o arquivo de exemplo em sample: { "data": "<base64>", "mime": "image/jpeg", "filename": "capa.jpg" } (imagem JPEG ou PNG até 5 MB, vídeo MP4 até 16 MB, PDF até 100 MB; o corpo da chamada aceita até 24 MB e o base64 aumenta o arquivo em um terço, então na prática o arquivo vai até uns 17 MB). Categoria UTILITY exige "utilityDeclared": true: a confirmação de que cada destinatário tem uma transação própria ligada à mensagem. Até 3 botões por template. O nome do template na Meta é gerado pelo sistema a partir do título.
/templates/{id}Um template, com o histórico de mudanças e o veredito do auditor de categoria (audit.level: compatible, risk ou marketing).
/templates/{id}Exclui o template na Meta. Um template aprovado que foi excluído não pode ser recriado com o mesmo nome por 30 dias.
Enviar um template a um atendimento
O mesmo POST /tickets/{id}/messages, com type: "template". É o único tipo que sai fora da janela de 24 horas. A regra da automação continua: atendimento com humano ou concluído responde 409.
{ "type": "template", "template": { "templateId": "…", "params": { "nome": "Maria" },
"header": { "link": "https://exemplo.com.br/capa.jpg" },
"buttons": [ { "index": 1, "text": "promo-outubro" } ] } }
Informe o template por templateId (ou por name e language). params traz o valor de cada variável pelo nome; falta de valor é 400. Cabeçalho de arquivo sem header usa o arquivo de exemplo guardado. Botão de link com variável leva buttons[].text; botão de copiar código leva buttons[].coupon. A resposta 201 traz message, ticket, template e window (open, lastInboundAt, closesAt). Template que não está aprovado responde 409 com reason: template_not_sendable. Há um teto de envios de template por dia por empresa (padrão 1.000, o provedor ajusta): acima dele, 429 com reason: broadcast_daily_cap.
Campanhas, listas importadas e lista de saída
A Central de disparo manda um template aprovado para muita gente de uma vez, com as proteções do número (vazão, limite diário da Meta, janela de horário, pausa automática, lista de saída). Estas rotas fazem pela API o que a tela de Disparos faz, com as mesmas regras, permissões e limites: a chave age como administradora da empresa inteira e a empresa precisa estar liberada pelo provedor (403 com reason: broadcast_off). O público é congelado no disparo: uma linha por pessoa, com os valores das variáveis já resolvidos.
/campaignsSem "launch": true, devolve só a revisão e não grava nada: destinatários válidos, cada exclusão por motivo (suppressed, agenda_only, recent, open_ticket, empty_variable…), custo máximo, limite do dia, ondas diárias e a janela de horário. Com "launch": true, dispara (ou agenda) e responde 201. O mesmo Idempotency-Key (ou requestId) devolve a mesma campanha com 200, sem disparar de novo. Campanha de marketing sem optIn.declaration: true não sai (422, reason: optin_missing). Teto por chave: 10 campanhas por hora (apiCampaignsPerHour, editável pelo provedor), com 429 acima disso.
POST /campaigns
Idempotency-Key: campanha-2026-10-lista-vip
{
"name": "Lista VIP outubro",
"templateId": "…",
"audience": { "tags": ["vip"], "exclude": { "tags": ["nao-incomodar"] }, "frequencyDays": 3 },
"variables": { "nome": { "from": "first_name", "default": "cliente" } },
"buttonVariables": { "0": { "from": "tracking" } },
"schedule": { "at": "2026-10-20T10:00:00-03:00" },
"pacing": { "mode": "random", "minSeconds": 5, "maxSeconds": 15 },
"reply": { "sectorId": "…", "targetStageId": "…" },
"optIn": { "source": "form", "declaration": true },
"launch": true
}
| Campo | O que é |
|---|---|
audience | De onde vem o público. Atalhos: tags (com tagsMode any ou all), stageIds (fases do Kanban, de GET /kanban/stages), sheet (a planilha da campanha: data em base64, CSV ou XLSX, com filename e mapping, ou até 1.000 contacts; vale só para esta campanha e não fica guardada), numbers (telefones colados: uma lista de textos ou um texto com um número por linha; o 55 é opcional), allContacts com confirmAllContacts: true (todos os contatos que já conversaram, nunca quem só veio da agenda do celular) e failedFrom (o id de outra campanha: quem falhou nela). Combine à vontade: vale a união, menos exclude (tags, stageIds, sheet, numbers), menos a lista de saída. Também aceita include e exclude como listas de partes ({ "type": "tags" | "stages" | "sheet" | "numbers" | "all" | "failed", … }). listId (lista importada) foi aposentado e responde 410. frequencyDays vai de 0 até o prazo de retenção da empresa (padrão 7). |
variables | Para cada variável do template, de onde vem o valor: first_name, name, phone, fixed (com value), column (coluna da planilha da campanha), field (campo personalizado do contato) ou previous (o mesmo valor da campanha de origem, só com failedFrom). default vale quando o valor vem vazio; sem valor, a pessoa é ignorada (empty_variable). |
buttonVariables | O valor de botão de link com variável ("0" é o primeiro botão) ou de copiar código. { "from": "tracking" } monta o texto de rastreio de cada pessoa para o fim da URL do botão: por padrão utm_source=whatsapp&utm_medium=campanha&utm_campaign={campanha}&ref={ref}. {ref} é um código opaco da linha (nunca o telefone) que também sai na coluna "Ref (rastreio)" do relatório em XLSX. Só vale em botão de link; value troca o modelo (só {campanha} e {ref} são variáveis). |
reply | sectorId (obrigatório): o setor onde as respostas viram atendimento, com a etiqueta campanha:nome. attributionHours: de 24 a 168, padrão 48. targetStageId: a fase do Kanban de destino. A primeira resposta cria o card do atendimento (se faltar) e o leva a essa fase. Exige o Kanban ligado e o setor das respostas igual ao setor do Kanban. |
schedule, pacing | schedule.at agenda (horário de Brasília se não houver fuso; até 60 dias). schedule.window troca a janela de horário (marketing: segunda a sábado, 9h às 20h). pacing é auto ou random com minSeconds e maxSeconds. |
optIn | source (whatsapp, form, store, event ou other, esta com sourceText) e declaration: true. A origem, o texto da declaração e a data ficam gravados na campanha. |
Números colados. audience.numbers (ou { "type": "numbers", "numbers": ["11 91234-5678", "+55 21 98765-4321"] } em include) usa os telefones só nesta campanha: não viram contato, lista nem etiqueta, ficam apenas nas linhas da fila da campanha (apagadas pela retenção). Aceita qualquer máscara, separados por linha, vírgula, ponto e vírgula ou tabulação; o 55 é opcional (DDD + número basta, com ou sem o 9 dos celulares antigos), número com + e outro país é recusado, e 8 ou 9 dígitos sem DDD são recusados. Repetidos contam uma vez. A revisão (POST /campaigns sem launch) devolve pasted com o total, os válidos, os repetidos, os inválidos e as 20 primeiras recusas com o motivo. Vale o limite de destinatários por campanha da empresa, a lista de saída e a declaração de opt-in como em qualquer público. {{nome}} usa o nome do contato salvo, se o número já for contato da empresa; senão, o valor reserva.
Quem falhou. audience.failedFrom monta uma campanha nova só com quem falhou em outra, depois de 24 horas: a Meta limita quantos templates de marketing cada pessoa recebe e insistir antes disso pode bloquear novas tentativas. Quem falhou há menos tempo fica de fora (excluded.retry_wait, com a hora em que libera em retry.waitUntil), e quem não existe no WhatsApp, pediu para sair ou tem número mal formado nunca volta (excluded.retry_recipient). A campanha nova pede a própria declaração de opt-in.
/campaignsAs campanhas, da mais recente para a mais antiga, com o funil de cada uma (progress) e os totais por situação (totals). Filtros status (scheduled, running, paused, completed, canceled), q, limit e offset.
/campaigns/{id}A campanha e as métricas: funil, taxas de entrega, leitura e resposta, falhas agrupadas por motivo (com o código da Meta), respostas em texto e cliques por botão, pedidos para sair, custo estimado (um teto) e apurado (entregues vezes a tarifa vigente; a fatura da Meta é a fonte da verdade), entrega ao longo do tempo e ondas diárias.
/campaigns/{id}/messagesOs destinatários com a situação de cada um (queued, sending, sent, delivered, read, failed, skipped, canceled, unknown), errorCode e error em português. Filtros state (ou replied), q, limit e offset.
/campaigns/{id}/report.xlsxO relatório em planilha: Resumo, Destinatários (com Ref (rastreio)), Falhas por motivo, Respostas, Entrega no tempo e Ondas. Os mesmos números da tela.
/campaigns/{id}/pause/campaigns/{id}/resume/campaigns/{id}/cancelPausa (agendada ou em envio), retoma (pausada; 409 se o número está desconectado ou o template deixou de estar aprovado) e cancela (o que estava na fila não sai). A pausa automática do sistema (taxa de falha, template pausado, qualidade ou limite do número) só se desfaz por resume, sempre por uma pessoa.
/broadcast-lists/broadcast-lists/broadcast-lists/{id}/broadcast-lists/{id}Aposentadas. As listas importadas não existem mais: as quatro rotas respondem 410 Gone com reason: "broadcast_lists_gone". A planilha agora vai dentro da campanha, em audience.sheet de POST /campaigns: data em base64 (CSV ou XLSX, o servidor reconhece pelo conteúdo) com mapping (phoneColumn, nameColumn e sheet, a aba, por número ou nome) ou até 1.000 contacts ({ "phone", "name", "data": { … } }). A planilha vale só para aquela campanha: o nome, o telefone e as colunas de cada pessoa ficam apenas nas linhas da campanha, que o sistema apaga 7 dias depois do fim dela (prazo editável pelo provedor). Telefone sai normalizado para +55 (fixo, DDD que não existe e número de fora são recusados com o motivo). A revisão (POST /campaigns sem launch) traz o relatório da leitura em sheet. Limite de linhas por empresa: maxListRows (padrão 20.000). Depois do prazo, GET /campaigns/{id} segue devolvendo os totais (enviadas, entregues, lidas, falhas por motivo, respostas, cliques por botão, custo, ondas, entrega no tempo), mas /campaigns/{id}/messages e /campaigns/{id}/report.xlsx respondem 410 e o campo purgedAt traz a data do apagamento.
/suppressions/suppressions/suppressions/{phone}A lista de saída: quem pediu para não receber marketing (pelo botão "Parar de receber", por palavra, pelo controle da Meta ou por você). O número não fica guardado: o sistema grava só um hash do número (com um segredo da empresa) e os 4 últimos dígitos, e GET devolve last4, o escopo, o motivo e a data. POST recebe phone (ou até 500 em phones) e scope: marketing (padrão) ou all. DELETE /suppressions/{phone} recebe o número inteiro, calcula o hash e remove. Nunca expira sozinha; tirar alguém dela fica na auditoria.
POST /campaigns sem launch) mostra o custo máximo e o limite diário antes de qualquer envio. Um webhook de saída pode acompanhar tudo: veja os eventos campaign.*, broadcast.message.* e template.status_changed em Avisos.Lida e digitando
/tickets/{id}/read{ } → dois tiques azuis na última mensagem do cliente
{ "typing": true } → tiques azuis e "digitando…"
Também zera as não lidas na fila. O "digitando…" some quando a resposta sai ou depois de 25 segundos; a Meta pede que ele só apareça quando uma resposta vem de fato. Segue as regras de quando a automação fala.
Passar para a equipe
Quando o cliente pede uma pessoa, ou a dúvida passa do que a automação resolve, transfira o atendimento. Para um setor, ele volta para a fila desse setor como aguardando. Para uma pessoa, ele já sai em atendimento com ela, no setor dela. Nos dois casos quem recebe vê a nota.
/sectors{ "sectors": [ { "id": "b3c1…", "name": "Comercial", "isDefault": true }, { "id": "9f2a…", "name": "Suporte", "isDefault": false } ], "defaultSectorId": "b3c1…" }
O setor padrão é onde caem as conversas novas.
/sectors{ "name": "Financeiro" }
→ 201 { "sector": { "id": "…", "name": "Financeiro", "isDefault": false, "active": true }, "restored": false }
Cria o setor (2 a 40 caracteres). Se já existe um arquivado com o mesmo nome, ele volta com o histórico (200, restored: true); um ativo com o mesmo nome dá 409.
/sectors/{id}{ "name": "Pós-venda" }
{ "active": false }
{ "default": true }
Renomeia (name), arquiva ou reativa (active) e escolhe o setor padrão das conversas novas (default: true; para trocar, marque outro setor, não existe default: false). As mesmas regras do painel: arquivar dá 409 com o motivo (reason) quando é o último setor ativo, quando é o padrão, ou quando ainda há atendente ou administrador sem outro setor ou atendimento não encerrado nele. Tudo é conferido antes de gravar. Excluir setor não existe na API. Responde { "sector": { … } }.
/agents{ "agents": [ { "id": "u-41…", "name": "Ana Ribeiro", "role": "agent", "sectorId": "b3c1…", "sectorName": "Comercial", "sectorIds": [ "b3c1…" ], "allSectors": false, "active": true } ] }
As pessoas ativas da empresa, sem nenhum dado de acesso (login, senha, e-mail). Só quem tem role: "agent" recebe transferência.
/tickets/{id}/transfer{ "sectorId": "9f2a…", "note": "Cliente quer trocar o produto; já passou o número do pedido" }
{ "userId": "u-41…", "note": "Cliente pediu para falar com a Ana" }
/tickets/{id}/close{ "note": "Dúvida resolvida pela automação" }
As duas respondem { "ticket": { … } } e geram os avisos ticket.transferred e ticket.closed. note é opcional, até 500 caracteres. No painel, o histórico mostra Automação como autor. Atendimento concluído recebe 409. Atendimento que uma pessoa já assumiu (em curso, com responsável) também: a automação não transfere nem conclui conversa iniciada por humano, e o responsável continua o mesmo.
/tickets/{id}/history{ "events": [ { "id": 41, "action": "ticket_transferred", "actorName": "Automação", "at": "…", "sectorName": "Suporte", "fromSectorName": "Comercial", "assignedName": null, "fromAssignedName": null, "status": null, "note": "…" } ] }
A linha do tempo do atendimento, do primeiro ao último evento (criou, assumiu, transferiu, concluiu, reiniciou).
/tickets/{id}/restartReinicia um atendimento concluído: ele volta para a fila (ou para quem estava com ele). Atendimento que não está concluído dá 409, e também dá 409 se o mesmo número já tem outro atendimento aberto (um aberto por número). Responde { "ticket": { … } }. Criar atendimento novo não existe na API.
Notas e etiquetas do atendimento
O cliente não vê nenhuma das duas, então valem em qualquer estado do atendimento, inclusive com um humano ou concluído.
/tickets/{id}/notes{ "text": "Cliente quer trocar o tamanho; pedido 4521, já pagou o frete" }
→ 201 { "note": { "id": "…", "text": "…", "source": "api", "author": "Automação", "apiKey": "n8n", "createdAt": "…" } }
Nota interna, até 2000 caracteres. É o jeito de a automação deixar o contexto para a pessoa que vai atender: no painel ela aparece no histórico do atendimento. GET /tickets/{id}/notes lista as notas, da mais antiga para a mais nova.
/tickets/{id}/tags{ "add": [ "vip", "boleto" ], "remove": [ "lead-frio" ] }
→ { "ticket": { …, "tags": [ "boleto", "vip" ] } }
Estas etiquetas são da conversa e servem à automação; a equipe usa as etiquetas do contato. Ficam em minúsculas, com até 40 caracteres, no máximo 30 por atendimento. Pôr uma que já está, ou tirar uma que não está, não dá erro. GET /tags lista as etiquetas da empresa com quantos atendimentos cada uma tem, e GET /tickets?tag=vip filtra por elas.
Contatos
O cadastro de cada número que já falou com a empresa, ou que a sua integração criou. O waId é o número só com dígitos, como a Meta usa.
/contacts?phone=5511999990000Busca por phone (com ou sem o nono dígito), por q (nome, e-mail ou o externalId exato) por tag, ou por field e value (o valor de um campo do contato), com limit, offset e hasMore como na lista de atendimentos. phone, q e tag se combinam entre si. field e value não se combinam com eles: quando field vem na busca, phone, q e tag são ignorados.
{ "contacts": [ { "waId": "5511999990000", "phone": "+5511999990000", "name": "Marina Lopes", "profileName": "Marina",
"email": "[email protected]", "externalId": "crm-77", "photoUrl": null, "tags": [ "vip" ], "createdAt": "…", "updatedAt": "…" } ],
"limit": 50, "offset": 0, "hasMore": false }
/contacts{ "phone": "+5511999990000", "name": "Marina Lopes", "email": "[email protected]", "externalId": "crm-77" }
Cria o contato (201) ou, se o número já existe, atualiza os campos enviados (200). name é o nome que a empresa dá ao contato e vence o nome do perfil do WhatsApp. externalId é o id do contato no seu CRM.
/contacts/{waId}O contato e os atendimentos dele, do mais recente para o mais antigo (até 20). É o histórico do cliente com a empresa.
/contacts/{waId}Muda só os campos enviados entre name, email e externalId; null apaga o campo. O name é do contato: aparece em todos os atendimentos do número, na fila, nos Relatórios e no Kanban, e o nome do perfil que o WhatsApp manda depois não o sobrescreve. Com name: null a fila volta ao nome do perfil (ou ao número). Vale também para um número que só tem atendimento, sem contato ainda: o contato é criado ao dar o nome. A mudança fica na auditoria como contact_renamed.
/contacts/{waId}/tags{ "add": [ "vip", "cliente-ativo" ], "remove": [ "lead-frio" ] }
→ { "contact": { …, "tags": [ "cliente-ativo", "vip" ] } }
Etiquetas do contato acompanham a pessoa em todos os atendimentos, e são as que a equipe vê e edita no painel. Seguem as mesmas regras das etiquetas de atendimento. Todo atendimento traz as do contato em contactTags, e GET /tags devolve também contactTags, com a cor escolhida no painel e quantos contatos cada uma tem.
/contacts/{waId}/notes/contacts/{waId}/notes{ "text": "Prefere contato à tarde" }
→ 201 { "phone": "+5511999990000", "notes": [ … ], "note": { "id": "…", "text": "…", "source": "api", "author": "Automação" } }
As anotações do contato são as mesmas da janela de anotações do painel: valem para todos os atendimentos do número (com ou sem o nono dígito). O GET lista, da mais nova para a mais antiga. O POST (até 2000 caracteres) grava no atendimento mais recente do número; número que nunca teve atendimento dá 404.
Catálogo de etiquetas do contato
As etiquetas que a equipe vê no painel (nome e cor). Colocar e tirar etiqueta de um contato é POST /contacts/{waId}/tags; aqui se cuida do catálogo da empresa.
/contact-tags{ "tags": [ { "tag": "vip", "color": "#ff0000", "contacts": 12 } ] }
/contact-tags{ "name": "cliente-ativo", "color": "#10b981" }
→ 201 { "tags": [ … ], "tag": "cliente-ativo" }
Cria a etiqueta no catálogo (1 a 40 caracteres, sem |, em minúsculas; até 200 por empresa; color é #rrggbb e opcional). Se ela já existe, só muda a cor.
/contact-tags/{tag}{ "name": "cliente", "color": "#3b82f6" }
Renomeia (em todos os contatos e cards) e/ou muda a cor. Etiqueta que não existe dá 404.
/contact-tags/{tag}Exclui a etiqueta de todos os contatos e cards.
Campos do contato
Os campos personalizados que o admin da empresa cria em Equipe → Configurações → Campos do contato: até 5, de texto livre, com até 2000 caracteres cada. Cada campo tem uma key, que sai do nome e não muda depois de criado; é por ela que a API lê e grava. Só funciona quando o responsável pela conta liberou os campos para a empresa; sem isso, estas rotas respondem 403.
/contact-fields{ "fields": [ { "key": "endereco", "name": "Endereço", "position": 1 }, { "key": "plano", "name": "Plano", "position": 2 } ] }
/contact-fields{ "name": "Data de nascimento" }
→ 201 { "fields": [ … ], "field": { "key": "data_de_nascimento", "name": "Data de nascimento", "position": 3 } }
Cria a definição de um campo (até 5 por empresa; 409 acima disso ou com chave repetida). A key sai do nome, ou você envia a sua (key: minúsculas sem acento, números e _).
/contact-fields/{key}{ "name": "Nascimento" }
Renomeia o campo; a chave nunca muda (400 se tentar).
/contact-fields/{key}Exclui o campo e os valores dele em todos os contatos; responde com deleted e quantos contatos tinham valor. Estas três só valem com os campos liberados para a empresa. Os valores de cada contato ficam em /contacts/{waId}/fields.
/contacts/{waId}/fields{ "phone": "+5511999990000", "fields": { "endereco": "Rua das Flores, 120", "plano": null } }
No lugar de {waId} vale o waId ou o número formatado com DDI, com ou sem o nono dígito: os dois são o mesmo contato. Por exemplo, GET /api/v1/contacts/5511999990000/fields e GET /api/v1/contacts/551199990000/fields devolvem os mesmos valores. Campo sem valor vem null.
/contacts/{waId}/fields{ "fields": { "plano": "Ouro", "endereco": null } }
Muda só as chaves enviadas; null ou texto vazio limpa o campo. Uma chave que não existe na empresa recusa o pedido inteiro (400), sem gravar nada. Responde com todos os campos do contato, no formato do GET.
/contacts/{waId}/fieldsLimpa todos os campos do contato.
/contacts?field=plano&value=OuroContatos do cadastro com esse valor no campo, igual, sem diferenciar maiúsculas. Paginado como a busca de contatos.
O valor dos campos não vai para o histórico de auditoria; fica registrado só que a chave mudou, e por qual chave de API.
Kanban
O Kanban da empresa tem um card por atendimento, no setor que o admin escolheu em Configurações → Kanban. A API lê e muda os cards, individualmente ou em massa; as fases, o setor e a regra de encerramento são só de leitura (o admin muda no painel, porque mexem na estrutura do quadro; os campos próprios dos cards, em /kanban/fields, também se definem pela API). A chave age pela empresa inteira, sem filtro de setor. A chave lê, cria, muda, move e exclui cards. Com o Kanban desligado, as rotas de cards respondem 409 com "reason": "kanban_off".
/kanban{ "kanban": { "enabled": true, "sector": { "id": "…", "name": "Comercial" }, "onCloseStageId": null, "autoCreate": false,
"stages": [ { "id": "…", "name": "Novo", "color": "#3b82f6", "position": 1 }, { "id": "…", "name": "Em atendimento", "color": "#f59e0b", "position": 2 }, … ] } }
onCloseStageId é a fase para onde o card vai quando o atendimento é encerrado, ou null para não mexer. autoCreate diz se o card nasce sozinho quando o atendimento nasce, é transferido ou é iniciado no setor do Kanban: empresa nova começa com false e só o admin liga, no painel. Com false, POST /kanban/cards continua criando o card normalmente.
/kanban/stages{ "stages": [ { "id": "…", "name": "Novo", "color": "#3b82f6", "position": 1 }, … ] }
Só as fases, para pegar os ids de stageId.
/kanban/cards?stageId=…&ownerId=…&tag=vip&updatedSince=2026-10-01T00:00:00Z&ticketId=…&phone=+5511999990000&q=Maria&limit=50&offset=0{ "cards": [ { "id": "…", "ticketId": "…", "title": "Maria Silva", "phone": "+5511999990000",
"stage": { "id": "…", "name": "Novo" }, "ownerUserId": null, "ownerName": null, "valueCents": 150000,
"dueDate": "2026-12-24", "note": "Ligar amanhã", "ticketClosed": false, "otherSector": false,
"tags": ["vip"], "fields": { "numero_do_pedido": "A-1" },
"version": 3, "createdAt": "2026-10-12T18:00:00.000Z", "movedAt": "…", "updatedAt": "…" } ],
"limit": 50, "offset": 0, "hasMore": false }
Todos os filtros são opcionais e se somam. ownerId é o responsável, tag é uma etiqueta do card e updatedSince (ISO 8601) traz só o que mudou depois, para sincronizar com um CRM. phone aceita o número com ou sem o nono dígito. q busca por nome ou telefone. valueCents é em centavos (inteiro) e dueDate é AAAA-MM-DD. tags são os nomes das etiquetas do card (as mesmas do catálogo dos contatos) e fields traz o valor de cada campo do card pela chave.
/kanban/cards/{id}Devolve { "card": … }, no mesmo formato. 404 se o card não existe nesta empresa.
/kanban/cards{ "ticketId": "…", "stageId": "…", "ownerUserId": "…", "valueCents": 150000, "dueDate": "2026-12-24",
"note": "Ligar amanhã", "tags": ["vip"], "fields": { "numero_do_pedido": "A-1" } }
→ 201 { "card": { … }, "created": true }
→ 200 { "card": { … }, "created": false } (o atendimento já tinha card: devolve o que existe)
É idempotente: repetir o pedido não cria um segundo card, porque cada atendimento tem um só. Só ticketId é obrigatório; os outros campos são opcionais e seguem as regras do PATCH abaixo. Sem stageId, o card nasce na primeira fase. Se algum dado opcional for recusado (400), o card já foi criado: corrija e repita o pedido (ele devolve o card existente e aplica os dados) ou use PATCH. Se o atendimento está em outro setor, a resposta é 409 com "reason": "other_sector".
/kanban/cards/{id}{ "stageId": "…", "ownerUserId": "…", "valueCents": 250000, "dueDate": "2026-11-30", "note": "Pediu desconto",
"tags": ["vip", "retorno"], "fields": { "numero_do_pedido": "A-1", "origem": null }, "version": 3 }
Muda só os campos enviados; null limpa responsável, valor, data e observação (até 2000 caracteres). tags é a lista inteira de etiquetas do card (até 30, até 40 caracteres cada, sem |). fields é um objeto chave: texto (até 2000 caracteres; null ou vazio limpa) e só aceita chaves de GET /kanban/fields; chave desconhecida dá 400. Com version (a que você leu), se outra pessoa mudou o card antes, a resposta é 409 com o card atual em card, e nada é gravado. Sem version, grava por cima.
/kanban/fields{ "fields": [ { "id": "…", "key": "numero_do_pedido", "name": "Número do pedido", "position": 1, "cards": 12 } ], "limit": 5 }
/kanban/fields{ "fields": [ { "id": "…", "name": "Pedido" }, { "name": "Origem", "key": "origem" } ] }
Define os campos próprios dos cards (até 5, texto livre), na ordem enviada. Quem tem id é renomeado (a chave não muda), quem não tem é criado (a chave sai do nome se você não enviar key) e quem falta é excluído, com os valores em todos os cards. Mais de 5 dá 409. Só chave com escopo de envio.
/kanban/cards/{id}/move{ "stageId": "…" }
→ { "card": { … } }
/kanban/cards/{id}→ { "deleted": true, "id": "…" }
/kanban/cards/bulk-move{ "ids": ["…", "…"], "stageId": "…" }
→ { "moved": 2 }
/kanban/cards/bulk-delete{ "ids": ["…", "…"] }
→ { "deleted": 2 }
As duas aceitam de 1 a 500 ids por chamada e são tudo ou nada: se algum id não existe nesta empresa, a resposta é 404 e nada muda. moved conta só os cards que de fato trocaram de fase. Cada card movido ou excluído gera o aviso kanban.card_moved ou kanban.card_deleted. Excluir não apaga o atendimento.
Limites. O Kanban é grátis e vem em todos os planos, com limites de uso justo. A criação de card (POST /kanban/cards) aceita até 60 chamadas por minuto por chave: acima disso a resposta é 429 com o cabeçalho retry-after (segundos). Cada empresa tem um teto de cards (50.000 por padrão): ao atingi-lo, POST /kanban/cards responde 409 com "Limite de cards da empresa atingido. Para liberar espaço, abra o menu ⋯ do Kanban e escolha Excluir os mais antigos, ou fale com a gente." e os cards automáticos deixam de nascer. Os cards de atendimentos encerrados há mais tempo que a retenção da empresa (180 dias por padrão) são apagados junto com o histórico.
Excluir o card não encerra nem apaga o atendimento. Nome, telefone e dados do contato não vão para o histórico de auditoria; só ids e a lista de campos que mudaram.
Relatórios
Os mesmos números da tela de Relatórios, por GET (chave de Leitura basta). A chave vale como administradora da empresa inteira, sem filtro de setor, e o período segue a regra do painel: horário de São Paulo, até 180 dias para trás.
/reports/summary?period=7d{ "period": { "key": "7d", "from": "2026-10-06", "to": "2026-10-12", "days": 7, "tz": "America/Sao_Paulo" },
"totals": { "contacts": 42, "uniquePeople": 38, "assumed": 30, "closed": 28, "transfers": 11, "openNow": 6, "waitingNow": 2 },
"byDay": [ … ], "bySector": [ … ], "agents": [ … só pessoas ], "automation": { "handled": 12, "assumed": 9, "closed": 5, "transfers": 3, "afterHours": 7, … }, "series": { "granularity": "day", "points": [ { "key": "2026-10-12", "contacts": 7, "transfers": 1 }, … ] }, "now": { "waiting": 3, "active": 5, "open": 8, "bySector": [ … ] }, "flows": [ … ], "busiestDay": { … }, "topSector": { … }, "topAgent": { … } }
/reports/contacts?period=month&q=Maria&page=1&pageSize=50/reports/people?period=6m&q=Douglas/reports/transfers?from=2026-10-01&to=2026-10-12/reports/contacts devolve atendimentos: um item por atendimento iniciado, então a mesma pessoa aparece várias vezes. /reports/people devolve contatos únicos, agrupados pelo telefone, cada um com attendances (atendimentos no período), lastAt e o setor, o atendente e a situação do último atendimento. Em agents entram só pessoas; o que a automação fez (IA, chave de API, sistema externo) vem em automation, com afterHours contando o que ocorreu fora de segunda a sexta, 08:00 às 18:00 (São Paulo).
now é a fila neste momento (aguardando, em curso e abertos por setor), sem relação com o período. A série do gráfico tem só contacts e transfers; a automação fica em automation.
Filtros das listas. /reports/contacts, /reports/people e /reports/transfers aceitam, além de q, status (waiting, active, closed ou open, que soma aguardando e em curso), sector (id do setor ou none) e agent (id da pessoa ou automation). Os filtros combinam entre si e com a paginação. A resposta traz filters com status, sector e agent, cada opção como { value, label, count }; a contagem de cada opção já considera os outros filtros e q. Em /reports/people os três são os do último atendimento; em /reports/transfers, situação é a atual do atendimento, setor é o de destino e atendente é quem transferiu.
As listas devolvem { "total", "page", "pageSize", "items": [ … ] } (pageSize até 200). No lugar de period (today, yesterday, 7d, month, 3m, 6m), valem from e to no formato AAAA-MM-DD. Período inválido dá 400. A planilha de exportação é só do painel.
Avisos (webhook)
O SyncAtende chama a URL do seu fluxo a cada mensagem do cliente e a cada mudança no atendimento. A empresa pode ter até 20 webhooks, cada um com nome, endereço, eventos e segredo próprios.
Vários webhooks
/webhooks{ "name": "CRM", "url": "https://crm.exemplo.com/hook", "events": ["message.received", "ticket.closed"] }
→ 201 { "webhook": { "id": "whk_…", "name": "CRM", "url": "…", "events": ["message.received", "ticket.closed"], "active": true, "lastDelivery": null }, "secret": "whsec_…" }
url é obrigatória. Sem name, o primeiro webhook se chama “Webhook principal” e os outros “Webhook 2”, “Webhook 3” e assim por diante (até 60 caracteres). Sem events, o webhook recebe todos. O secret aparece só nessa resposta. Ao chegar em 20 webhooks, o cadastro devolve 409.
| Rota | O que faz |
|---|---|
GET /webhooks | Lista os webhooks (nome, url, eventos, active e última entrega) e o limit. Nunca traz o segredo. |
GET /webhooks/{id} | Lê um webhook. |
PATCH /webhooks/{id} | Muda só o que for enviado: name, url, events ou active (false pausa). Não troca o segredo e, se mudar a url, zera a última entrega. |
DELETE /webhooks/{id} | Exclui o webhook. O segredo dele deixa de valer. |
POST /webhooks/{id}/test | Manda um aviso ping só para esse webhook, mesmo pausado, e devolve { "delivered": true, "status": 200, "event": "ping" }. |
POST /webhooks/{id}/secret | Gera um segredo novo, devolvido uma vez na resposta. O anterior para de valer na hora. |
Como a entrega funciona. Cada evento vai para todos os webhooks ativos que o escolheram, cada um assinado com o próprio segredo e de forma independente: um destino fora do ar não atrasa nem impede os outros. Cada aviso leva o cabeçalho X-SyncAtende-Webhook-Id com o id do webhook que o recebe, para o seu fluxo saber qual segredo usar na conferência. Webhook pausado não recebe nada, a não ser o teste.
Rota legada: um webhook só
As rotas abaixo (/webhook, no singular) continuam funcionando como antes, sobre o primeiro webhook da empresa (o mais antigo). Quem já tinha um webhook o encontra como “Webhook principal”, com o mesmo segredo, endereço e eventos. Em código novo, prefira /webhooks.
/webhook{ "url": "https://seu-n8n/webhook/syncatende", "events": ["message.received", "ticket.assumed"] }
→ { "webhook": { "url": "…", "events": ["message.received", "ticket.assumed"], "lastDelivery": null }, "secret": "whsec_…" }
O secret aparece só nessa resposta; um novo PUT com url troca o segredo. A URL precisa ser https (http só para localhost). Também existem GET /webhook (URL, eventos escolhidos e resultado da última entrega), DELETE /webhook e POST /webhook/test (manda um aviso ping e devolve { "delivered": true, "status": 200, "event": "ping" }).
Escolher os eventos
events é a lista dos eventos que o webhook recebe. Sem o campo, o cadastro novo recebe todos e um PUT com url mantém a escolha atual. Para mudar só a escolha, mande events sem url: o segredo e o endereço não mudam, e a resposta não traz secret.
PUT /webhook { "events": ["message.received", "message.status"] }
→ { "webhook": { "url": "…", "events": ["message.received", "message.status"], "lastDelivery": null } }
Foto, áudio, vídeo e documento no webhook. Quando a mensagem tem mídia, o campo message.media traz, além de mime, filename e size, o downloadUrl: um link https público e assinado que baixa o arquivo direto (no n8n, um nó HTTP Request com “Response: File”), sem chave de API. O link vale 7 dias, serve só para aquela mensagem e deixa de valer se o segredo do webhook for trocado. Se available for false, a cópia ainda está sendo baixada: tente o link de novo em alguns segundos. O link tem o formato /api/v1/media/{companyId}/{messageId}?e=…&s=…. O campo url (caminho da API, com a chave) continua igual.
No painel a empresa escolhe pelos nomes em português; na API e no JSON enviado à automação o nome é o técnico (message.received etc.), que não muda, para não quebrar fluxos que já existem. A lista precisa ter pelo menos 1 evento e só nomes técnicos da tabela abaixo; senão a resposta é 400, em português, com o nome que não existe e a lista dos válidos. Escolher eventos antes de cadastrar o endereço dá 409. Evento que não foi escolhido não é enviado e não conta como falha. O ping do POST /webhook/test sai sempre.
Eventos
| Nome no painel | Nome técnico (event) | Quando |
|---|---|---|
| Mensagem recebida | message.received | O cliente mandou mensagem. A mídia já vem baixada. |
| Mensagem enviada pelo atendente (celular ou WhatsApp Web) | message.sent | A empresa mandou uma mensagem pelo celular ou pelo WhatsApp Web (eco da Meta, só na API oficial). Mesmo formato do message.received, com direction: "outbound" e source: "echo"; ticket pode ser null. Traz edição e exclusão (message.type edit ou revoke). Não avisa o que a empresa envia pela API e não diz qual atendente mandou. |
| Mensagem enviada (status: enviada, entregue, lida ou falhou) | message.status | Uma mensagem enviada pela empresa mudou de status: sent, delivered, read ou failed (com o motivo em message.error). Traz message e ticket. |
| Atendimento assumido | ticket.assumed | Um humano clicou em Iniciar. A automação deve parar. |
| Atendimento transferido (distribuição para outro setor ou atendente) | ticket.transferred | O atendimento mudou de setor ou de pessoa. |
| Atendimento encerrado | ticket.closed | O atendimento foi concluído. |
| Atendimento reiniciado | ticket.restarted | O atendimento foi reaberto. |
| Card criado | kanban.card_created | Um atendimento ganhou card no Kanban. |
| Card movido de fase | kanban.card_moved | O card mudou de fase (por uma pessoa, pela API ou ao encerrar o atendimento). Traz from e to, cada um com id e name da fase. |
| Card atualizado | kanban.card_updated | Responsável, valor, data prevista, observação, etiquetas, campos do card ou o selo de atendimento encerrado mudaram. |
| Card excluído | kanban.card_deleted | O card foi excluído. Na exclusão em massa, um aviso por card. |
| Campanha criada | campaign.created | A campanha foi disparada ou agendada, com o público congelado. Traz campaign (id, nome, situação, categoria, template, destinatários) e progress (o funil). |
| Campanha iniciada | campaign.started | Começou a enviar (no disparo, ou na hora do agendamento). |
| Campanha pausada | campaign.paused | Parou, por uma pessoa ou sozinha. Traz reason (em português) e pauseKind (user, auto, template ou account). |
| Campanha retomada | campaign.resumed | Uma pessoa retomou a campanha pausada. |
| Campanha concluída | campaign.completed | A fila acabou. Traz o funil final em progress. |
| Campanha cancelada | campaign.canceled | Uma pessoa cancelou. canceledMessages é quantas saíram da fila. |
| Onda diária iniciada | campaign.wave_started | Uma campanha grande começou um novo dia de envio (o limite diário da Meta divide o envio em ondas). Traz wave. |
| Mensagem de campanha enviada | broadcast.message.sent | A Meta aceitou a mensagem de um destinatário. Alto volume. |
| Mensagem de campanha entregue | broadcast.message.delivered | Chegou ao celular. Alto volume. |
| Mensagem de campanha lida | broadcast.message.read | O destinatário leu. Alto volume. |
| Mensagem de campanha não enviada | broadcast.message.failed | Falhou, com message.errorCode (código da Meta) e message.error em português. Alto volume. |
| Destinatário respondeu à campanha | broadcast.message.replied | A primeira resposta (texto ou botão). Traz reply (kind, payload, title), ticketId e replyTag. |
| Destinatário pediu para sair | broadcast.message.opted_out | Quem recebeu a campanha pediu para não receber marketing (botão ou palavra). Já entrou na lista de saída. |
| Template mudou na Meta | template.status_changed | Mudou o status, a categoria ou a qualidade de um template (também o aviso prévio de 24 horas de mudança de categoria, como category_notice). Traz template, change (field, from, to), reason e via (webhook ou sync). |
Campanhas e templates. Os eventos campaign.*, broadcast.message.* e template.status_changed só chegam com a Central de disparo liberada e só aos webhooks que os escolheram. As mensagens de campanha não geram message.status: os dois mundos não se misturam, para não inundar as automações que já existem. broadcast.message.* é de volume alto (um aviso por destinatário e por mudança de status, dezenas de milhares numa campanha grande): a entrega passa por uma fila própria de cada webhook, com no máximo 4 entregas ao mesmo tempo, para uma campanha não derrubar o seu servidor. Se o seu servidor for mais lento que a campanha, os avisos esperam na fila (até 20.000 por webhook; passando disso, o mais antigo é descartado e vira log). Escolha só o que a automação usa.
X-SyncAtende-Event: broadcast.message.delivered
{ "event": "broadcast.message.delivered", "deliveryId": "…", "at": "2026-10-20T13:02:11.000Z",
"campaign": { "id": "cmp_…", "name": "Lista VIP outubro", "category": "MARKETING" },
"message": { "id": "…", "ref": "3f9a1c0d22be", "phone": "+5511999990000", "name": "Maria", "state": "delivered",
"wamid": "wamid.…", "wave": 1, "errorCode": null, "error": null,
"sentAt": "…", "deliveredAt": "…", "readAt": null, "failedAt": null, "repliedAt": null } }
POST https://seu-n8n/webhook/syncatende
X-SyncAtende-Event: message.received
X-SyncAtende-Signature: sha256=<hex>
{ "event": "message.received", "deliveryId": "…", "at": "2026-09-29T18:43:01.000Z",
"ticket": { "id": "…", "status": "waiting", "assignedUserId": null, … },
"message": { "id": "wamid.…", "text": "Quero ajuda", "choice": null, "media": null, … },
"automation": { "canReply": true, "reason": null } }
automation.reason explica quando não pode responder: human (com um atendente) ou closed.
Conferir a assinatura
X-SyncAtende-Signature é o HMAC-SHA256 do corpo cru, com o seu segredo, em hexadecimal e com o prefixo sha256=. No n8n (nó Code) ou em Node:
const crypto = require("crypto");
const esperado = "sha256=" + crypto.createHmac("sha256", SEGREDO).update(corpoCru, "utf8").digest("hex");
const valido = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(assinaturaRecebida));
Os quatro eventos do Kanban trazem o card no campo card: id, ticketId, title, phone, stage (id e name), ownerUserId, valueCents, dueDate, note, ticketClosed, tags (lista de nomes), fields (chave e texto), createdAt e movedAt. Webhook que já existia antes do Kanban continua recebendo só os seis primeiros eventos; o admin liga os novos em Escolher eventos, ou você manda a lista em events. Webhook novo nasce com os dez.
X-SyncAtende-Event: kanban.card_moved
{ "event": "kanban.card_moved", "deliveryId": "…", "at": "2026-10-12T18:43:01.000Z",
"card": { "id": "…", "ticketId": "…", "title": "Maria Silva", "stage": { "id": "…", "name": "Aguardando" }, … },
"from": { "id": "…", "name": "Novo" }, "to": { "id": "…", "name": "Aguardando" } }
Entrega
Seu fluxo deve responder com status 2xx em até 10 segundos. Sem isso, o SyncAtende tenta de novo depois de 2 s e depois de 10 s, três vezes no total. Resposta 4xx (menos 429) não se repete, porque o problema está no destino. A mensagem que a Meta reentrega não gera um segundo aviso.
Fluxo de um agente de IA
- Chega
message.received. Seautomation.canReplyforfalse, não faça nada. POST /tickets/{id}/readcom{"typing": true}.- Se precisar de contexto,
GET /tickets/{id}/messages; se houver mídia, baixe pelaurl. - Responda com
POST /tickets/{id}/messages: texto, botões para triagem, lista, mídia. - Se o cliente pedir uma pessoa, deixe o resumo em
POST /tickets/{id}/notese transfira comPOST /tickets/{id}/transfer, para o setor certo ou direto para uma pessoa deGET /agents. Quando alguém da equipe clicar em Iniciar, chegaticket.assumede o SyncAtende recusa novas respostas da automação. - Se a automação resolveu,
POST /tickets/{id}/close.
n8n e curl
No n8n, use o nó HTTP Request: Authentication → Generic Credential Type → Header Auth, com o nome Authorization e o valor Bearer syncatende_… (guarde numa credencial, nunca no fluxo). Em Send Body escolha JSON. Em Options → Response, para baixar um arquivo, escolha File. Para repetir sem duplicar, acrescente o cabeçalho Idempotency-Key com o id da execução ({{ $execution.id }}) mais um sufixo por chamada. Ligue Retry On Fail só em chamadas com Idempotency-Key ou em GET.
# descobrir as fases e criar um card já na fase certa
curl -s https://app.syncatende.com.br/api/v1/kanban/stages -H "Authorization: Bearer $SYNCATENDE_KEY"
curl -s -X POST https://app.syncatende.com.br/api/v1/kanban/cards \
-H "Authorization: Bearer $SYNCATENDE_KEY" -H "Content-Type: application/json; charset=utf-8" \
-H "Idempotency-Key: crm-lead-9981" \
-d '{ "ticketId": "…", "stageId": "…", "valueCents": 150000, "tags": ["vip"] }'
# só o que mudou nos cards desde ontem
curl -s "https://app.syncatende.com.br/api/v1/kanban/cards?updatedSince=2026-10-11T00:00:00Z" -H "Authorization: Bearer $SYNCATENDE_KEY"
# mover vários cards de uma vez
curl -s -X POST https://app.syncatende.com.br/api/v1/kanban/cards/bulk-move \
-H "Authorization: Bearer $SYNCATENDE_KEY" -H "Content-Type: application/json" \
-d '{ "ids": ["…", "…"], "stageId": "…" }'
Erros e limites
Todo erro volta como { "error": "motivo em português" }.
| Status | Quando |
|---|---|
400 | Corpo inválido: tipo desconhecido, limite da Meta, mídia fora do formato, texto que não é UTF-8, mensagem citada de outra conversa. |
401 | Chave ausente, errada ou revogada. |
403 | Chave antiga de somente leitura tentando agir (enviar, marcar como lida, transferir, concluir, mexer nos webhooks, gravar campos do contato, criar, mover ou excluir cards). Chave nova nunca recebe este 403. A mensagem de erro diz que a chave é só de leitura. Também: campos do contato não liberados para a empresa. |
404 | Atendimento, mensagem, contato ou card não existe para esta chave. O dado de outra empresa responde como se não existisse. |
409 | A automação não pode falar agora: humano no atendimento, atendimento concluído, fora das 24 horas. Kanban desligado (reason: kanban_off) e conflito de version no card. Também quando um pedido com a mesma Idempotency-Key ainda está em andamento. |
429 | Mais de 60 criações de card por minuto na mesma chave. O cabeçalho retry-after diz em quantos segundos tentar de novo. É o único limite de frequência da API; os demais são de tamanho: corpo de até 24 MB, limit até 200 por página, 500 ids por ação em massa. |
422 | Idempotency-Key já usada em outra rota. Template com texto fora das regras (lista errors) ou recusado pela Meta. |
502 | A Meta recusou. O motivo dela vem no texto do erro. |
503 | Nenhum número conectado ao SyncAtende. |
OpenAPI
O contrato completo da API, em OpenAPI 3.1, está em https://app.syncatende.com.br/api/v1/openapi.json. Não precisa de chave e traz cada rota, parâmetros, corpos, respostas, o formato de erro, o esquema bearerAuth e o tipo de cada rota (x-scope: read só consulta, write age e public não pede chave). Toda chave nova alcança todas elas; só as chaves antigas de somente leitura ficam restritas às rotas read. Importe no Postman, no Insomnia ou no n8n, ou gere um cliente em TypeScript ou Python com qualquer gerador de OpenAPI.