Como importar contatos em massa via API

Quando usar

• Você precisa importar ou atualizar vários contatos no Cloud Chat de uma vez via API
• Você quer fazer upsert (criar novos + atualizar existentes) na mesma chamada
• Você precisa de funcionalidades avançadas como tags granulares, lookup de variantes de telefone ou merge de JSONB

Pré-requisitos

• API Key em mãos — ver Como encontrar sua API Key no Cloud Chat

• CLOUDCHAT_DOMAIN e ACCOUNT_ID

• Cada contato deve ter ao menos um identificador entre phone_number, email ou identifier

Endpoint

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

Headers

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",
      "additional_attributes": {
        "company": "Acme",
        "city": "São Paulo"
      },
      "custom_attributes": {
        "plano": "premium",
        "origem": "campanha-março"
      }
    },
    {
      "name": "Contato 2",
      "phone_number": "+5511888887777"
    }
  ]
}

Campos por contato

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

Flag upsert

Exemplo de requisição

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"
      }
    ]
  }'

Resposta

Sucesso (HTTP 201)

{ "success": true }

Erro de validação ou conflito (HTTP 422)

{
  "success": false,
  "errors": [
    {
      "index": 0,
      "attributes": { "name": "Contato 1", "email": "[email protected]" },
      "errors": ["Email is invalid"]
    },
    {
      "index": 1,
      "attributes": { "name": "Contato 2" },
      "errors": "Duplicate: Contact with this phone number already exists"
    }
  ]
}

• index indica a posição (0-based) da linha no array data
• errors por linha pode ser array de validação ou string única para conflitos de chave (duplicidade)

Body vazio (HTTP 400)

Retornado quando data é nulo ou array vazio.

Cuidados com upsert

PUT /api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}}

Comportamento avançado (opcional)

A partir de 30/04/2026, o endpoint aceita parâmetros opcionais no body para customizar o processamento. Todos têm default conservador (paridade com o comportamento anterior) — só envie se quiser habilitar novas funcionalidades.

Combinações que exigem atenção

tags_add e tags_remove no body

Para adicionar e remover tags de forma granular por contato. Ignorados silenciosamente se você não enviar apply_tags: true (ou api_version: "v2").

{
  "api_version": "v2",
  "data": [
    {
      "email": "[email protected]",
      "tags_add": ["vip", "premium"],
      "tags_remove": ["pending"]
    }
  ]
}

A ordem é determinística: primeiro adiciona, depois remove. Se uma mesma tag aparecer nos dois arrays, a remoção ganha.

Removendo chaves JSONB com __DELETE__

Para remover uma chave específica de additional_attributes ou custom_attributes sem mexer nas demais, envie o valor literal "__DELETE__". Requer respect_sentinel: true (ou api_version: "v2").

{
  "api_version": "v2",
  "data": [
    {
      "email": "[email protected]",
      "custom_attributes": {
        "favorite_color": "__DELETE__"
      }
    }
  ]
}

Funciona apenas em chaves de primeiro nível dos objetos JSONB. Combine com merge_jsonb: "shallow" (já incluso em api_version: "v2") para preservar as outras chaves.

Lookup de variantes de telefone (BR mobile-9)

Com normalize_lookup: true (ou api_version: "v2"), o sistema busca contatos existentes por variantes do telefone enviado.

{
  "api_version": "v2",
  "data": [
    {
      "phone_number": "+5511933334444",
      "name": "Maria"
    }
  ]
}

Se já existe um contato com +551133334444 (sem o 9), ele é encontrado e atualizado — em vez de criar duplicado.

Coalesce de null (preservar campos existentes)

Com coalesce_nulls: true, valores null no payload são tratados como "preservar valor existente". Útil quando você gera o payload programaticamente.

{
  "coalesce_nulls": true,
  "data": [
    {
      "email": "[email protected]",
      "name": null,
      "phone_number": "+5511999998888"
    }
  ]
}

Sem coalesce_nulls, o name seria apagado. Com coalesce_nulls: true, o name existente é preservado.

Detecção de ambiguidade (AMBIGUOUS_MATCH)

Se uma linha contiver dois ou mais campos chave (email, telefone, identifier) que apontem para contatos diferentes já existentes, a linha é rejeitada com erro AMBIGUOUS_MATCH.

Diferença entre este endpoint e o Import individual

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

• Para importar apenas 1 contato: Como importar um contato individual via API

• Para importar via HubSpot workflows: Como importar contatos via HubSpot

• Para remover tags em massa: Como remover tags de contatos em massa via API

• Visão geral de todas as APIs disponíveis: Guia Mestre — Como acessar e operar dados do Cloud Chat via API