Principal API e integrações | Chaves, endpoints e webhooks Como criar, atualizar e deletar contatos via API

Como criar, atualizar e deletar contatos via API

Última atualização em Sep 23, 2026

A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá.

Quando usar

  • Você precisa criar, consultar, atualizar ou excluir um contato específico no Cloud Chat via API
  • Você quer alterar apenas alguns campos de um contato sem apagar os demais
  • Você está integrando o Cloud Chat a outro sistema que gerencia contatos individualmente

Pré-requisitos

Este artigo cobre operações em um contato por vez pelo endpoint REST padrão. Para importar ou atualizar vários contatos de uma vez, use Como importar contatos em massa via API. Para apenas ler dados, veja Como consultar contatos, tickets e mensagens em tempo real via API.

Permissões por operação

Operação Permissão mínima
Criar, consultar, atualizar Qualquer perfil de agente
Deletar contato Administrador
Consultar por e-mail (/contacts/email) Administrador

Se você consegue criar e atualizar mas recebe 403 Forbidden ao deletar, seu token é de agente. Use um token de usuário administrador para excluir contatos.

Criar contato

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

O body é um objeto JSON simples — pelo menos um entre email, phone_number ou identifier:

{
  "name": "Maria Silva",
  "email": "[email protected]",
  "phone_number": "+5511999998888",
  "identifier": "CRM-123",
  "additional_attributes": { "company_name": "Acme" },
  "custom_attributes": { "plano": "premium" }
}

  • Opcional: envie inbox_id (e source_id) para já vincular o contato a uma caixa de entrada.

  • Resposta 200 com o contato criado, incluindo o id.

Consultar contato

Por id:

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

Por e-mail exato (requer administrador):

GET https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/[email protected]

Para buscar por texto livre (nome, telefone, empresa, parcial), use o endpoint de busca — ver Como consultar contatos, tickets e mensagens em tempo real via API, seção "Buscar contatos por texto livre".

Atualizar contato

PUT https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

Envie apenas os campos que quer alterar:

{
  "name": "Maria S. Silva",
  "custom_attributes": { "plano": "enterprise" }
}

Diferente do import em massa com upsert: true, o update individual não apaga os campos que você não enviar.

  • custom_attributes são mesclados com os já existentes (não zeram os demais).

  • Para remover um atributo customizado específico:

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

{ "custom_attributes": ["plano"] }
  • Resposta 200 com o contato atualizado.

Deletar contato

DELETE https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/contacts/{CONTACT_ID}

  • Requer usuário administrador.

  • Resposta 200 em caso de sucesso.

Se o contato estiver online no momento da chamada, a exclusão é bloqueada e retorna 422. Tente novamente quando ele não estiver ativo.

Para remover apenas tags de contatos (sem excluir o contato), veja Como remover tags de contatos em massa via API.

Exemplo de requisição (atualizar)

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 '{ "name": "Maria S. Silva" }'

Erros comuns

Status Significado
403 Forbidden Token sem permissão (deletar exige administrador)
422 Unprocessable Entity Dados inválidos, ou tentativa de deletar contato online
404 Not Found Contato não encontrado na conta

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