Contatos

Gerencie contatos (clientes e leads) da sua conta. Contatos podem ter conversas em multiplos canais e atributos personalizados.

GET/api/v1/accounts/{account_id}/contacts

Lista todos os contatos da conta com paginacao e ordenacao.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`sort`(query)	`string`	Nao	Campo de ordenacao: name, email, phone_number, last_activity_at, created_at
`page`(query)	`integer`	Nao	Numero da pagina

curl -s "https://chat.seudominio.com/api/v1/accounts/1/contacts?sort=name&page=1" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de contatos paginada

json

{
  "meta": { "count": 150, "current_page": 1 },
  "payload": [
    {
      "id": 456,
      "name": "Joao Silva",
      "email": "joao@empresa.com",
      "phone_number": "+5511999999999",
      "thumbnail": "https://...",
      "custom_attributes": { "plano": "premium" },
      "created_at": "2026-01-10T10:00:00.000Z"
    }
  ]
}

POST/api/v1/accounts/{account_id}/contacts

Cria um novo contato na conta.

Body

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`	`number`	Sim	ID do inbox para associar o contato
`name`	`string`	Nao	Nome completo do contato
`email`	`string`	Nao	Email do contato
`phone_number`	`string`	Nao	Telefone com codigo do pais (+5511...)
`avatar_url`	`string`	Nao	URL da foto de perfil
`identifier`	`string`	Nao	Identificador externo unico (ex: ID do seu sistema)
`custom_attributes`	`object`	Nao	Atributos personalizados como chave-valor
`blocked`	`boolean`	Nao	Bloquear contato

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/contacts" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 1,
    "name": "Maria Santos",
    "email": "maria@empresa.com",
    "phone_number": "+5511988888888",
    "custom_attributes": {
      "plano": "enterprise",
      "empresa": "Tech Corp"
    }
  }'

200Contato criado

json

{
  "id": 457,
  "name": "Maria Santos",
  "email": "maria@empresa.com",
  "phone_number": "+5511988888888",
  "custom_attributes": { "plano": "enterprise", "empresa": "Tech Corp" },
  "created_at": "2026-02-15T14:00:00.000Z"
}

GET/api/v1/accounts/{account_id}/contacts/{id}

Retorna detalhes completos de um contato, incluindo conversas e atributos.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`id`(path)	`integer`	Sim	ID numerico do contato

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/contacts/456" \
  -H "api_access_token: YOUR_TOKEN" | jq .

PUT/api/v1/accounts/{account_id}/contacts/{id}

Atualiza os dados de um contato existente.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Nao	Nome completo
`email`	`string`	Nao	Email
`phone_number`	`string`	Nao	Telefone
`avatar_url`	`string`	Nao	URL da foto
`custom_attributes`	`object`	Nao	Atributos personalizados

bash

curl -X PUT "https://chat.seudominio.com/api/v1/accounts/1/contacts/456" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Joao Silva Jr",
    "custom_attributes": { "plano": "enterprise" }
  }'

DELETE/api/v1/accounts/{account_id}/contacts/{id}

Remove permanentemente um contato e todas as suas conversas.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`id`(path)	`integer`	Sim	ID numerico do contato

bash

curl -X DELETE "https://chat.seudominio.com/api/v1/accounts/1/contacts/456" \
  -H "api_access_token: YOUR_TOKEN"

200Contato deletado com sucesso

GET/api/v1/accounts/{account_id}/contacts/search

Busca contatos por nome, email, telefone ou identificador.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`q`(query)	`string`	Sim	Termo de busca
`page`(query)	`integer`	Nao	Pagina
`sort`(query)	`string`	Nao	Ordenacao
`include_contacts`(query)	`boolean`	Nao	Incluir contatos inativos

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/contacts/search?q=joao" \
  -H "api_access_token: YOUR_TOKEN" | jq .

GET/api/v1/accounts/{account_id}/contacts/{id}/conversations

Lista todas as conversas de um contato especifico.

Parametros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numerico da conta
`id`(path)	`integer`	Sim	ID numerico do contato

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/contacts/456/conversations" \
  -H "api_access_token: YOUR_TOKEN" | jq .

Inboxes do Contato

GET/api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes

Lista os inboxes em que o contato pode ser contatado.

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/contacts/456/contactable_inboxes" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Inboxes do contato

json

{
  "payload": [
    {
      "source_id": "abc123",
      "inbox": {
        "id": 1,
        "name": "WhatsApp",
        "channel_type": "Channel::Whatsapp"
      }
    }
  ]
}

POST/api/v1/accounts/{account_id}/contacts/{contact_id}/contact_inboxes

Associa o contato a um novo inbox.

Body

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`	`integer`	Sim	ID do inbox para associar

POST/api/v1/accounts/{account_id}/actions/contact_merge

Mescla dois contatos duplicados em um unico registro.

Body

Nome	Tipo	Obrigatorio	Descricao
`base_contact_id`	`integer`	Sim	ID do contato que sera mantido
`mergee_contact_id`	`integer`	Sim	ID do contato que sera mesclado e removido

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/actions/contact_merge" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_contact_id": 456,
    "mergee_contact_id": 789
  }'

Etiquetas do Contato

GET/api/v1/accounts/{account_id}/contacts/{id}/labels

Lista as etiquetas de um contato.

200Etiquetas do contato

json

{ "payload": ["vip", "lead-quente"] }

POST/api/v1/accounts/{account_id}/contacts/{id}/labels

Define as etiquetas de um contato.

Body

Nome	Tipo	Obrigatorio	Descricao
`labels`	`array`	Sim	Array de etiquetas

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/contacts/456/labels" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["vip", "lead-quente", "enterprise"] }'