Como importar contatos em massa via API

Neste artigo, você vai aprender a importar ou atualizar vários contatos de uma vez no Cloud Chat via API, usando o endpoint de criação em lote.

Para importar ou atualizar vários contatos de uma vez via API no Cloud Chat, envie uma requisição POST para o endpoint abaixo.

Quer importar apenas um contato? Use o endpoint de Import de Contato individual. Os dois endpoints têm formatos de body diferentes — não misture.

Endpoint

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

Headers

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

Corpo da Requisição

O body usa um array data contendo os contatos a serem importados:

{
  "upsert": true,
  "data": [
    {
      "name": "Contato 1",
      "email": "[email protected]",
      "phone_number": "+5511999998888",
      "identifier": "EXT-001",
      "custom_attributes": {
        "plano": "premium",
        "origem": "campanha-março"
      }
    },
    {
      "name": "Contato 2",
      "phone_number": "+5511888887777"
    }
  ]
}

Campos por contato

Campo	Obrigatório	Descrição
`phone_number`	Pelo menos 1 dos 3*	Telefone no formato internacional com `+`
`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
`custom_attributes`	Não	Objeto com atributos customizados (chave-valor)

*Cada contato deve ter pelo menos um entre phone_number, email ou identifier.

Flag `upsert`

Valor	Comportamento
`false` ou ausente	Apenas cria contatos novos. Se já existir, ignora.
`true`	Cria contatos novos e atualiza contatos existentes.

Exemplo de requisição (curl)

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/bulk_create' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{
    "upsert": true,
    "data": [
      {
        "name": "Contato 1",
        "email": "[email protected]",
        "phone_number": "+5511999998888"
      },
      {
        "name": "Contato 2",
        "phone_number": "+5511888887777"
      }
    ]
  }'

Cuidados com upsert

Atenção — risco de perda de dados com upsert: true:

Ao atualizar um contato existente via bulk_create com upsert: true, qualquer campo que você não enviar será sobrescrito com null.

Exemplo: Se um contato tem email e phone_number cadastrados, e você envia um update com apenas phone_number, o campo email será apagado.

Se você precisa atualizar apenas alguns campos sem apagar os demais, use o endpoint de update individual:
PUT /api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}}

Diferença entre este endpoint e o Import individual

	Este endpoint (`bulk_create`)	Import individual (`external_import`)
Quando usar	Importar/atualizar vários contatos de uma vez	Importar/atualizar 1 contato por chamada
Formato do body	`{"upsert": true, "data": [{...}, {...}]}`	Objeto JSON simples (flat)
Upsert	Precisa do flag `"upsert": true`	Sempre ativo (automático)
Cuidado com null	Campos omitidos são sobrescritos com `null`	Campos omitidos são preservados

Não misture os formatos! Se enviar um objeto flat (sem data: [...]) para este endpoint, não vai funcionar. Para contato individual, use o endpoint de import individual.

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