Contatos

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

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

Lista todos os contatos da conta com paginação e ordenação.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`sort`(query)	`string`	Nao	Campo de ordenação: name, email, phone_number, last_activity_at, created_at
`page`(query)	`integer`	Nao	Número da página
`labels`(query)	`string`	Nao	Filtra os contatos por etiqueta(s) (qualquer uma das informadas)
`include_contact_inboxes`(query)	`boolean`	Nao	Quando "true", inclui as associações de inbox (contact_inboxes) de cada contato na resposta

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": { "segmento": "vip" },
      "created_at": 1768039200
    }
  ]
}

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

Cria um novo contato na conta.

Body

Nome	Tipo	Obrigatorio	Descricao
`name`	`string`	Nao	Nome completo do contato
`email`	`string`	Nao	Email do contato
`phone_number`	`string`	Nao	Telefone com código do país (+5511...)
`avatar_url`	`string`	Nao	URL da foto de perfil (baixada de forma assíncrona)
`identifier`	`string`	Nao	Identificador externo único (ex: ID do seu sistema)
`custom_attributes`	`object`	Nao	Atributos personalizados como chave-valor
`additional_attributes`	`object`	Nao	Atributos adicionais (cidade, país, empresa, etc.)
`blocked`	`boolean`	Nao	Bloquear contato
`inbox_id`	`integer`	Nao	ID do inbox para criar uma associação contact_inbox. Opcional — sem ele o contato é criado sem inbox.
`source_id`	`string`	Nao	ID de origem usado na associação contact_inbox (quando inbox_id é enviado)

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": {
      "segmento": "vip",
      "empresa": "Tech Corp"
    }
  }'

200Contato criado (aninhado em payload.contact; created_at é inteiro epoch)

json

{
  "payload": {
    "contact": {
      "id": 457,
      "name": "Maria Santos",
      "email": "maria@empresa.com",
      "phone_number": "+5511988888888",
      "custom_attributes": { "segmento": "vip", "empresa": "Tech Corp" },
      "created_at": 1771164000
    },
    "contact_inbox": null
  }
}

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

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

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`id`(path)	`integer`	Sim	ID numérico 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
`identifier`	`string`	Nao	Identificador externo único
`avatar_url`	`string`	Nao	URL da foto
`blocked`	`boolean`	Nao	Bloquear contato
`custom_attributes`	`object`	Nao	Atributos personalizados (mesclados com os existentes)
`additional_attributes`	`object`	Nao	Atributos adicionais (mesclados com os existentes)

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": { "segmento": "vip" }
  }'

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

Remove permanentemente um contato e os dados associados. Ação irreversível.

Operação destrutiva e irreversível

Esta operação executa um hard delete: remove o contato e os registros associados de forma permanente, sem recuperação. Sempre verifique o id e confirme que ele pertence à conta correta antes de chamar. O id é resolvido estritamente dentro da conta autenticada — IDs não são globais. A API retorna erro 422 se o contato estiver online no momento. Para conformidade LGPD, prefira o endpoint lgpd_delete (abaixo), que registra a solicitação e executa a exclusão de forma auditável.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`id`(path)	`integer`	Sim	ID do contato (escopado à conta autenticada)

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.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`q`(query)	`string`	Sim	Termo de busca
`page`(query)	`integer`	Nao	Página
`sort`(query)	`string`	Nao	Ordenação
`include_contact_inboxes`(query)	`boolean`	Nao	Quando "true", inclui as associações de inbox (contact_inboxes) de cada contato na resposta

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 específico.

Parâmetros

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

bash

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

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

Retorna histórico cronológico (mais recente primeiro) de todos os atendimentos de um contato. Profissional, serviço e parceiro são carregados em eager-load.

Licença e permissão

Histórico de atendimentos está incluído em toda licença NooviChat válida; o acesso depende das permissões do usuário e da configuração operacional da conta.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`contact_id`(path)	`integer`	Sim	ID numérico do contato
`page`(query)	`integer`	Nao	Número da página (padrão 1, 50 por página)

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

200Histórico de atendimentos paginado

json

{
  "data": [
    {
      "id": 1,
      "public_id": "550e8400-e29b-41d4-a716-446655440000",
      "scheduled_at": "2026-05-04T10:00:00Z",
      "ends_at": "2026-05-04T11:00:00Z",
      "status": "completed",
      "notes": "Limpeza profilática",
      "price_cents": 15000,
      "currency": "BRL",
      "cancelled_at": null,
      "cancellation_reason": null,
      "professional": { "id": 1, "name": "Dr Maria Silva", "color": "#10B981" },
      "service": { "id": 7, "name": "Limpeza Dental", "duration_minutes": 60 },
      "partner": { "id": 3, "name": "Unimed" },
      "created_at": "2026-04-30T15:32:00Z"
    }
  ],
  "meta": {
    "total": 23
  }
}

404Contato não encontrado

json

{ "error": "Contact not found" }

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
`source_id`	`string`	Nao	Identificador de origem do contato no canal (ex: número/telefone no inbox). Útil para integrações que precisam definir o source_id externo da associação.

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

Mescla dois contatos duplicados em um único registro.

Body

Nome	Tipo	Obrigatorio	Descricao
`base_contact_id`	`integer`	Sim	ID do contato que será mantido
`mergee_contact_id`	`integer`	Sim	ID do contato que será 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", "conta-chave"] }'