Como importar um contato individual via API

Neste artigo, você vai aprender a importar ou atualizar um contato individual no Cloud Chat via API.

Para importar ou atualizar um contato individual via API no Cloud Chat, envie uma requisição POST para o endpoint abaixo com sua chave de acesso e os campos necessários.

Quer importar vários contatos de uma vez? Use o endpoint de Import em massa de contatos 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

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

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

Exemplo de requisição (curl)

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 um novo contato ou atualiza um existente 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

Importante: 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 resultado.

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 vai buscar pelo email primeiro (pois o campo email está presente). Se [email protected] não existir em nenhum contato, ele não vai tentar buscar pelo phone_number. O resultado será uma tentativa de criar um contato novo, que pode falhar silenciosamente por conflito de telefone.

Como fazer corretamente

Para atualizar um contato existente por telefone, envie apenas o telefone como identificador na primeira chamada, sem o campo que deseja adicionar como identificador:

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

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

Diferença entre este endpoint e o Import em massa

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

Onde encontrar os parâmetros de configuração

• CLOUDCHAT_DOMAIN: O domínio visível na URL do navegador ao acessar o Cloud Chat

• ACCOUNT_ID: Em configurações da conta

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