Símbolo da AmivuSímbolo da AmivuDevelopers

Contatos

Quem está do outro lado, e como manter o cadastro em sincronia com o seu.

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

POST /v1/contacts é encontre ou crie. Antes de criar, a Amivu procura a pessoa na organização, nesta ordem:

  1. pelo external_id, quando ele veio;
  2. pelo phone, em qualquer formato e com ou sem o nono dígito do celular;
  3. pelo email, só quando o cadastro não traz telefone.

Achou: o contato é atualizado com os campos que vieram no corpo, e a resposta é o mesmo contato, com 201. Etiquetas e campos personalizados são somados aos que ele já tem, nunca tirados. O telefone de quem foi achado pelo telefone fica como estava, e o external_id só é gravado no contato que ainda não tem um. Não achou: o contato é criado. Um telefone novo é uma pessoa nova, mesmo com um e-mail que já existe.

Terminal
curl https://api.amivu.com.br/v1/contacts \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "João Silva", "phone": "+55 11 99999-9999", "tags": ["tag_01K7ZFB2C4D6E8F0G2H4J6K8M0"] }'

É o que permite mandar todo cadastro do formulário do seu site, e rodar a sincronização inteira do seu CRM de novo, sem criar ninguém em dobro. Dois envios da mesma pessoa ao mesmo tempo também acabam num contato só.

Telefone da empresa
Duas pessoas que dividem o mesmo telefone viram um contato só. Para mantê-las separadas, mande um external_id diferente para cada uma: um external_id que ainda não está na base é uma pessoa nova, e o telefone só acha contato que não tem um.

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

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

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

Terminal
# 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.

O campo pode ter um formato, escolhido no painel e lido em type (number, currency, date, single_select, multi_select, boolean), com as opções em options. O valor continua texto, no formato que o painel e os formulários gravam: número como 1.5, moeda em centavos (1290), data como 2026-11-17, os rótulos da múltipla escolha separados por , e Sim ou Não. A API grava o texto como ele vier; o que estiver fora do formato aparece no painel como foi escrito.

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: o que não veio na lista sai. Serve para quem é dono da lista inteira, como um CRM que espelha as etiquetas dele.

Para só acrescentar, use POST /v1/contacts/{id}/tags. As etiquetas que o contato já tem ficam, inclusive as que a equipe pôs à mão no atendimento, e a que ele já carrega é ignorada: repetir a chamada não muda nada. Se uma das etiquetas não existir na organização, nada é gravado e a resposta é 404 tag_not_found.

Terminal
curl https://api.amivu.com.br/v1/contacts/cnt_01K7ZFA5X8Q2M4N6P8R0T2V4W6/tags \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["tag_01K7ZFB2C4D6E8F0G2H4J6K8M0"] }'

DELETE /v1/contacts/{id}/tags/{tag_id} tira uma só e mantém as outras. As duas rotas pedem o alcance contacts:write e devolvem o contato atualizado. Cada etiqueta que entra gera um tag.added, e cada uma que sai, um tag.removed. A exceção é a etiqueta de origem de um canal ou de uma Entrada posta de uma vez em quem já tinha chegado por ali: essa arrumação da base não gera aviso. Quem chega depois gera, como em qualquer etiqueta.

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.

O número é gravado só com dígitos, e com o 55 na frente quando é brasileiro e veio sem o código do país: (11) 98765-4321 vira 5511987654321. Vale para a API e para o painel; o que o visitante digita no chat do site fica como foi digitado. Na busca, o filtro phone aceita o número em qualquer formato, e no celular acha também a forma com ou sem o nono dígito.

Veja também Sincronizar um CRM.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.