Principal APIs Como importar um contato individual via API

Como importar um contato individual via API

Última atualização em May 21, 2026

Quando usar

  • Você precisa criar ou atualizar um contato por vez no Cloud Chat via API
  • Você quer um endpoint mais simples e que preserva campos não enviados (não sobrescreve com null)
  • Você está integrando com um sistema externo que emite eventos individuais (ex: novo cadastro)

Pré-requisitos

Quer importar vários contatos de uma vez? Use o endpoint de Como importar contatos em massa via API. Os dois endpoints têm formatos de body diferentes — não misture.

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import

Headers

Header Valor
content-type application/json
api_access_token Seu token de API

Corpo da requisição

O body é um objeto JSON simples (flat), sem arrays. Pelo menos um dos campos phone_number, identifier ou email deve estar presente.

{
  "phone_number": "+5599123456789",
  "identifier": "CUSTOM_ID",
  "email": "[email protected]",
  "name": "Nome do Contato",
  "company_name": "Empresa X",
  "tags": "tag1, tag2, tag3",
  "ATRIBUTO_CUSTOMIZADO": "valor"
}

Campos disponíveis

Campo Obrigatório Descrição
phone_number Pelo menos 1 dos 3* Telefone em E.164 com + (ex: +5511999998888)
email Pelo menos 1 dos 3* E-mail do contato
identifier Pelo menos 1 dos 3* Identificador externo único
name Não Nome do contato
company_name Não Nome da empresa
tags Não Tags separadas por vírgula
Campos customizados Não Use a chave do atributo customizado cadastrado no Cloud Chat

*Pelo menos um entre phone_number, email ou identifier deve ser informado.

Exemplo de requisição

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{
    "phone_number": "+5599123456789",
    "name": "Nome do Contato",
    "email": "[email protected]",
    "company_name": "Empresa X",
    "tags": "tag1, tag2"
  }'

Comportamento de criação e atualização (upsert)

Este endpoint cria ou atualiza automaticamente. Para decidir se o contato já existe, o sistema busca na seguinte ordem de prioridade:

  1. Primeiro busca por email

  2. Se não enviou email, busca por identifier

  3. Se não enviou identifier, busca por phone_number

A busca usa apenas o primeiro campo disponível na ordem acima. Ela não tenta os campos seguintes se o primeiro não encontrar.

Lookup de variantes (BR mobile-9)

Este endpoint individual faz lookup exato por phone_number. Se você precisa criar/atualizar contatos com lookup de variantes (ex.: você envia +5511933334444 e o contato existe como +551133334444), use o endpoint de Import em massa com api_version: "v2" (ou normalize_lookup: true).

Mudança a partir de 30/04/2026: a busca por variantes está disponível apenas no caminho bulk.

O que isso significa na prática

Se você quer atualizar um contato que já existe pelo telefone (ex: adicionar um e-mail), e envia:

{
  "phone_number": "+5511999998888",
  "email": "[email protected]"
}

O sistema busca pelo email primeiro (porque o campo email está presente). Se [email protected] não existe em nenhum contato, ele não tenta buscar pelo phone_number — vai tentar criar um contato novo, que pode falhar silenciosamente por conflito de telefone.

Como fazer corretamente

Para atualizar um contato existente por telefone, faça o flow em duas etapas:

Passo 1 — Localize o contato (se precisar do ID):

curl -X GET \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/search?q=+5511999998888' \
  --header 'api_access_token: SEU_TOKEN'

Passo 2 — Atualize via endpoint de update individual:

curl -X PUT \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{"email": "[email protected]"}'

Resposta

Status Significado
204 No Content Requisição processada (sem corpo de resposta)
422 Unprocessable Entity Erro de validação

O status 204 indica que a requisição foi recebida, mas não retorna o contato criado/atualizado. Se precisar confirmar a alteração, faça uma consulta após a chamada.

Diferença entre este endpoint e o Import em massa

Este endpoint (external_import) Import em massa (bulk_create)
Quando usar Importar/atualizar 1 contato por chamada Importar/atualizar vários contatos
Formato do body Objeto JSON simples (flat) {"upsert": true, "data": [{...}]}
Upsert Sempre ativo (automático) Precisa do flag "upsert": true
Resposta 204 No Content (sem corpo) 201 Created com resultado

Não misture os formatos. Se enviar {"upsert": true, "data": [...]} para este endpoint, não vai funcionar. Esse formato é exclusivo do endpoint de import em massa.

Onde encontrar os parâmetros

  • CLOUDCHAT_DOMAIN — domínio visível na URL do navegador

  • ACCOUNT_ID — em Configurações da conta

  • API_TOKEN — em https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings

Observações