Skip to main content

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](/books/api-e-integracoes/page/o-que-a-api-v3-faz-e-como-comecar)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

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

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

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

  3. De volta: crie a assinatura do evento contact.updated no formato 3 (o que esta receita espera). Pela tela de Ajustes (Canais e integrações → 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