Contatos

Um contato é a pessoa do outro lado. Ele existe uma vez por organização e acompanha todas as conversas dela, em todos os canais — o mesmo João no WhatsApp e no chat do site é um contato só.

O objeto

{
  "object": "contact",
  "id": "cnt_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "name": "João Silva",
  "first_name": "João",
  "last_name": "Silva",
  "email": "joao@empresa.com.br",
  "phone": "+5511999999999",
  "external_id": "customer_8291",
  "avatar_url": null,
  "tags": [{ "object": "tag", "id": "tag_01K7...", "name": "VIP", "color": "#8b5cf6" }],
  "custom_fields": { "cpf": "000.000.000-00", "plano": "enterprise" },
  "metadata": { "erp_id": "29819" },
  "created_at": "2026-08-26T21:42:19.238Z",
  "updated_at": "2026-08-26T21:42:19.238Z"
}

Como não duplicar ninguém

Mande o external_id. Quando ele já existe na organização, a criação devolve o contato existente sem alterá-lo e responde 201. É o que permite rodar a sincronização inteira do seu CRM de novo sem medo.

curl https://api.amivu.com.br/v1/contacts \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "João Silva", "external_id": "customer_8291" }'

Para atualizar sem saber o id da Amivu, procure primeiro e use o que voltar:

curl "https://api.amivu.com.br/v1/contacts?external_id=customer_8291" \
  -H "Authorization: Bearer $AMIVU_API_KEY"

Fields personalizados

Diferente de metadata, um campo personalizado aparece: ele é visível no atendimento, filtra listas e alimenta variáveis de disparo. Por isso ele precisa existir no catálogo antes de ser preenchido.

# 1. crie a definição, uma vez
curl https://api.amivu.com.br/v1/custom-fields \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Plano", "scope": "contact" }'

# 2. preencha por contato, sempre pela CHAVE
curl -X PATCH https://api.amivu.com.br/v1/contacts/cnt_01K7... \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "plano": "enterprise" } }'

Uma chave desconhecida é recusada, e não ignorada: um CRM que mande cpff em vez de cpf merece saber na hora, e não descobrir meses depois que metade da base está sem o campo. Mandar null apaga o valor.

Etiquetas

Uma etiqueta marca a pessoa, e não o atendimento. Ela acompanha o contato em todas as conversas, filtros e disparos — é o único vínculo que existe, e é por isso que aplicar etiqueta por uma conversa também é aplicar ao contato dela.

Mandar tags num PATCH substitui a lista atual. É como se remove uma etiqueta sem uma rota própria.

O telefone pode ser nulo

Nem todo contato chega com telefone. Alguém que escreve pelo chat do site é anônimo até se identificar; no WhatsApp, quem escreve num grupo pode aparecer com um identificador que não é um número.

phone: null é o estado honesto de “ainda não sabemos”. Quando o número aparece, ele preenche o mesmo contato — o histórico não se parte em dois.

Veja também Sincronizar um CRM.