Sincronizar contatos com o seu sistema

Se seu sistema (ERP, planilha, outro CRM) é a fonte da verdade dos seus contatos, você quer mantê-los sincronizados com o AtendeBot nos dois sentidos: seu sistema envia atualizações para cá, e o AtendeBot avisa quando um contato muda por aqui (ex.: um atendente editou o e-mail no atendimento).
Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por O que a API v3 faz e como começar.
Objetivo
Criar ou atualizar contatos pelo telefone a partir do seu sistema, em um contato por vez ou em lote, e receber de volta as mudanças feitas no AtendeBot.
Pré-requisitos
Token de API com escopos 
contacts:write e 
contacts:read: veja Gerar tokens de API para integrações.
Um endpoint seu para receber o webhook de volta (opcional, só para o passo 3 abaixo; o que é um webhook: Configurar webhooks para sistemas externos).
Tempo estimado
15 minutos.
Caminho de acesso
Chamada direta à API: não há tela equivalente no AtendeBot para sincronização em lote vinda de fora.
Passo a passo
Criar ou atualizar um contato pelo telefone, num único contato: use 
if_exists: "update" para que a mesma chamada funcione tanto na primeira sincronização (cria) quanto nas seguintes (atualiza). O telefone precisa vir com DDI, em E.164:
curl -X POST https://api.atende.bot/public/v3/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "phone": "5511999998888",
    "email": "maria@exemplo.com",
    "if_exists": "update"
  }'
Sem 
if_exists, telefone já cadastrado responde 
409 CONFLICT, proteção contra duplicata quando você quer só criar.
Em lote, até 500 contatos por chamada, em 
POST /contacts/batch (só criação, não aceita 
if_exists):
curl -X POST https://api.atende.bot/public/v3/contacts/batch \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Maria Souza", "phone": "5511999998888" },
    { "name": "João Lima", "phone": "5521988887777" }
  ]'
A resposta traz 
meta.partial: true quando algum item falha depois de gravar (ex.: tag inexistente); cada falha aparece em 
failed, com o índice do item no campo 
field.
De volta: crie a assinatura do evento 
contact.updated no formato 3 (o que esta receita espera). Pela tela de Ajustes (API e webhooks → Webhooks) ela já nasce nesse formato: no diálogo, "Formato do payload" fica em v3, e o botão 
{ } ao lado de cada evento abre o envelope de exemplo. Ou pela API:
curl -X POST https://api.atende.bot/public/v3/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sincronizar contatos: de volta",
    "url": "https://SEU-ENDPOINT/webhooks/contact-updated",
    "events": [{ "name": "contact.updated" }],
    "secret": "UM_SEGREDO_SEU"
  }'
A entrega traz 
data.contact (o contato já carregado: 
id, 
name, 
phone, 
email, 
tags...) e 
data.changed, a lista dos campos que mudaram. Na maioria dos casos você nem precisa buscar de novo; se precisar do contato completo, use 
GET /public/v3/contacts/{{ $json.data.contact.id }} ou 
GET /public/v3/contacts/phone:5511999998888 (o prefixo 
phone: funciona como referência direta).
Resultado esperado
Contato criado ou atualizado a partir do seu sistema; mudanças feitas por aqui chegam de volta pelo webhook 
contact.updated.
Erros comuns
Sintoma: 
400 PHONE_REQUIRES_COUNTRY_CODE. Solução: 10-11 dígitos é faixa ambígua, sempre envie com código do país, ex.: 
5511999998888.
Sintoma: 
409 CONFLICT ao criar. Solução: telefone já existe, use 
if_exists: "update".
Artigos relacionados
O que a API v3 faz e como começar
Configurar webhooks para sistemas externos
Abrir um card no CRM quando chega uma mensagem