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

RegraO que acontece
O atendimento está com um humanoRecusa com 409. Quando alguém clica em Iniciar no painel, a conversa passa a ser dele.
O atendimento foi concluídoRecusa com 409.
O cliente não escreve há mais de 24 horasRecusa 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…ChamadaOnde vem
Setor (e qual é o padrão)GET /sectorssectors[].id, defaultSectorId
Pessoa da equipeGET /agentsagents[].id, com setores e papel
Fase do KanbanGET /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 cardGET /kanban/fieldsfields[].key (é a chave usada em fields do card)
Campo do contatoGET /contact-fieldsfields[].key
EtiquetasGET /tagstags (do atendimento) e contactTags (do catálogo, com color); as do card são as do catálogo do contato
Card de um atendimentoGET /kanban/cards?ticketId=…cards[0].id
Atendimento de um númeroGET /tickets?phone=5511999990000tickets[].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

GET/tickets?status=waiting

Lista 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âmetroFiltra
statuswaiting (aguardando), active (com um humano) ou closed.
sectorId, assignedUserIdSetor ou pessoa responsável.
tagAtendimentos com essa etiqueta.
phoneNúmero do cliente, com ou sem o nono dígito.
updatedSinceMudou desde essa data (ISO 8601). Para sincronizar um CRM, guarde a hora da última leitura e peça só o que mudou.
limit, offsetTamanho 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.

GET/tickets/{id}

Um atendimento só, no mesmo formato: { "ticket": { … } }.

Ler mensagens

GET/tickets/{id}/messages?limit=50

As ú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"
} ] }
CampoSignificado
directioninbound (do cliente) ou outbound (da empresa).
typetext, image, audio, video, document, sticker, reaction, interactive, buttons, list, cta_url, entre outros.
replyToId da mensagem citada. Numa reação, a mensagem reagida.
choiceA opção que o cliente tocou: { "id": "setor:financeiro", "title": "Financeiro" }. Vale para botão, lista e resposta rápida de mensagem-modelo.
interactiveNas mensagens enviadas com botões ou lista, o que foi oferecido.
mediaArquivo da mensagem, com url para baixar. Veja Mídia.
statusDas enviadas: accepted → sent → delivered → read (ou played, voz ouvida), ou failed. Só avança, mesmo que a Meta avise fora de ordem.
errorQuando failed: { "code": 131047, "title": "…", "details": "…" }, o motivo que a Meta deu.
sourcecloud_api (pela API), echo (enviada pelo celular ou WhatsApp Web) ou history (sincronização).
GET/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

POST/tickets/{id}/messages

Um 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.

Envie o corpo em UTF-8. Acentos em outra codificação chegam estragados, e o SyncAtende recusa com 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 } }
typeFormatosTamanhoLegenda
JPEG, PNGimage5 MBsim
MP4, 3GPPvideo16 MBsim
AAC, AMR, MP3, M4A, OGGaudio16 MBnão
qualquerdocument100 MBsim, e filename
WebPsticker500 KBnã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

GET/messages/{id}/media

Devolve 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://…" }
typeLimites
buttons1 a 3 botões; title até 20, id até 256; text até 1024.
listbutton 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_urllabel até 20; url https; text até 1024.
todosheader 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.

GET/templates

Lista 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.

POST/templates

Cria 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.

GET/templates/{id}

Um template, com o histórico de mudanças e o veredito do auditor de categoria (audit.level: compatible, risk ou marketing).

DELETE/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.

Template de marketing é cobrado pela Meta por mensagem entregue, até dentro da janela de 24 horas, direto no método de pagamento da conta da empresa. O SyncAtende não revende nem repassa esse custo.

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.

POST/campaigns

Sem "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
}
CampoO que é
audienceDe 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).
variablesPara 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).
buttonVariablesO 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).
replysectorId (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, pacingschedule.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.
optInsource (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.

GET/campaigns

As 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.

GET/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.

GET/campaigns/{id}/messages

Os 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.

GET/campaigns/{id}/report.xlsx

O 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.

POST/campaigns/{id}/pause
POST/campaigns/{id}/resume
POST/campaigns/{id}/cancel

Pausa (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.

GET/broadcast-lists
POST/broadcast-lists
GET/broadcast-lists/{id}
DELETE/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.

GET/suppressions
POST/suppressions
DELETE/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.

Marketing é cobrado pela Meta por mensagem entregue, no método de pagamento da conta da empresa. A revisão (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

POST/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.

GET/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.

POST/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.

PATCH/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": { … } }.

GET/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.

POST/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" }
POST/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.

GET/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).

POST/tickets/{id}/restart

Reinicia 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.

POST/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.

POST/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.

GET/contacts?phone=5511999990000

Busca 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 }
POST/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.

GET/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.

PATCH/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.

POST/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.

GET/contacts/{waId}/notes
POST/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.

GET/contact-tags
{ "tags": [ { "tag": "vip", "color": "#ff0000", "contacts": 12 } ] }
POST/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.

PATCH/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.

DELETE/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.

GET/contact-fields
{ "fields": [ { "key": "endereco", "name": "Endereço", "position": 1 }, { "key": "plano", "name": "Plano", "position": 2 } ] }
POST/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 _).

PATCH/contact-fields/{key}
{ "name": "Nascimento" }

Renomeia o campo; a chave nunca muda (400 se tentar).

DELETE/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.

GET/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.

PATCH/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.

DELETE/contacts/{waId}/fields

Limpa todos os campos do contato.

GET/contacts?field=plano&value=Ouro

Contatos 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".

GET/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.

GET/kanban/stages
{ "stages": [ { "id": "…", "name": "Novo", "color": "#3b82f6", "position": 1 }, … ] }

Só as fases, para pegar os ids de stageId.

GET/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.

GET/kanban/cards/{id}

Devolve { "card": … }, no mesmo formato. 404 se o card não existe nesta empresa.

POST/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".

PATCH/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.

GET/kanban/fields
{ "fields": [ { "id": "…", "key": "numero_do_pedido", "name": "Número do pedido", "position": 1, "cards": 12 } ], "limit": 5 }
PUT/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.

POST/kanban/cards/{id}/move
{ "stageId": "…" }
→ { "card": { … } }
DELETE/kanban/cards/{id}
→ { "deleted": true, "id": "…" }
POST/kanban/cards/bulk-move
{ "ids": ["…", "…"], "stageId": "…" }
→ { "moved": 2 }
POST/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.

GET/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": { … } }
GET/reports/contacts?period=month&q=Maria&page=1&pageSize=50
GET/reports/people?period=6m&q=Douglas
GET/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

POST/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.

RotaO que faz
GET /webhooksLista 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}/testManda um aviso ping só para esse webhook, mesmo pausado, e devolve { "delivered": true, "status": 200, "event": "ping" }.
POST /webhooks/{id}/secretGera 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.

PUT/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 painelNome técnico (event)Quando
Mensagem recebidamessage.receivedO cliente mandou mensagem. A mídia já vem baixada.
Mensagem enviada pelo atendente (celular ou WhatsApp Web)message.sentA 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.statusUma mensagem enviada pela empresa mudou de status: sent, delivered, read ou failed (com o motivo em message.error). Traz message e ticket.
Atendimento assumidoticket.assumedUm humano clicou em Iniciar. A automação deve parar.
Atendimento transferido (distribuição para outro setor ou atendente)ticket.transferredO atendimento mudou de setor ou de pessoa.
Atendimento encerradoticket.closedO atendimento foi concluído.
Atendimento reiniciadoticket.restartedO atendimento foi reaberto.
Card criadokanban.card_createdUm atendimento ganhou card no Kanban.
Card movido de fasekanban.card_movedO 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 atualizadokanban.card_updatedResponsável, valor, data prevista, observação, etiquetas, campos do card ou o selo de atendimento encerrado mudaram.
Card excluídokanban.card_deletedO card foi excluído. Na exclusão em massa, um aviso por card.
Campanha criadacampaign.createdA 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 iniciadacampaign.startedComeçou a enviar (no disparo, ou na hora do agendamento).
Campanha pausadacampaign.pausedParou, por uma pessoa ou sozinha. Traz reason (em português) e pauseKind (user, auto, template ou account).
Campanha retomadacampaign.resumedUma pessoa retomou a campanha pausada.
Campanha concluídacampaign.completedA fila acabou. Traz o funil final em progress.
Campanha canceladacampaign.canceledUma pessoa cancelou. canceledMessages é quantas saíram da fila.
Onda diária iniciadacampaign.wave_startedUma 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 enviadabroadcast.message.sentA Meta aceitou a mensagem de um destinatário. Alto volume.
Mensagem de campanha entreguebroadcast.message.deliveredChegou ao celular. Alto volume.
Mensagem de campanha lidabroadcast.message.readO destinatário leu. Alto volume.
Mensagem de campanha não enviadabroadcast.message.failedFalhou, com message.errorCode (código da Meta) e message.error em português. Alto volume.
Destinatário respondeu à campanhabroadcast.message.repliedA primeira resposta (texto ou botão). Traz reply (kind, payload, title), ticketId e replyTag.
Destinatário pediu para sairbroadcast.message.opted_outQuem recebeu a campanha pediu para não receber marketing (botão ou palavra). Já entrou na lista de saída.
Template mudou na Metatemplate.status_changedMudou 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

  1. Chega message.received. Se automation.canReply for false, não faça nada.
  2. POST /tickets/{id}/read com {"typing": true}.
  3. Se precisar de contexto, GET /tickets/{id}/messages; se houver mídia, baixe pela url.
  4. Responda com POST /tickets/{id}/messages: texto, botões para triagem, lista, mídia.
  5. Se o cliente pedir uma pessoa, deixe o resumo em POST /tickets/{id}/notes e transfira com POST /tickets/{id}/transfer, para o setor certo ou direto para uma pessoa de GET /agents. Quando alguém da equipe clicar em Iniciar, chega ticket.assumed e o SyncAtende recusa novas respostas da automação.
  6. 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" }.

StatusQuando
400Corpo inválido: tipo desconhecido, limite da Meta, mídia fora do formato, texto que não é UTF-8, mensagem citada de outra conversa.
401Chave ausente, errada ou revogada.
403Chave 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.
404Atendimento, mensagem, contato ou card não existe para esta chave. O dado de outra empresa responde como se não existisse.
409A 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.
429Mais 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.
422Idempotency-Key já usada em outra rota. Template com texto fora das regras (lista errors) ou recusado pela Meta.
502A Meta recusou. O motivo dela vem no texto do erro.
503Nenhum 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.