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:
- pelo
external_id, quando ele veio; - pelo
phone, em qualquer formato e com ou sem o nono dígito do celular; - 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.
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ó.
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:
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.
# 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.
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.