Contatos

Um contato é a pessoa do outro lado da conversa. Pela API você cria, busca, atualiza, organiza por labels e associa contatos aos seus inboxes.

Base e autenticação

As rotas desta página são relativas a /api/v1/accounts/{account_id} na base https://appchat01.interleads.chat e exigem o cabeçalho api_access_token. Veja Autenticação.

Endpoints

Método	Rota	Descrição
GET	/contacts	Lista contatos (query: sort, page)
POST	/contacts	Cria um contato
GET	/contacts/{id}	Detalhes de um contato
PUT	/contacts/{id}	Atualiza um contato
DELETE	/contacts/{id}	Exclui um contato
GET	/contacts/{id}/conversations	Lista as conversas do contato
GET	/contacts/search	Busca por texto (query: q, sort, page)
POST	/contacts/filter	Filtro avançado (corpo com filtros)
POST	/contacts/{id}/contact_inboxes	Associa o contato a um inbox (retorna source_id)
GET	/contacts/{id}/contactable_inboxes	Inboxes em que o contato pode ser contatado
GET	/contacts/{id}/labels	Lista as labels do contato
POST	/contacts/{id}/labels	Define as labels do contato (substitui o conjunto)
POST	/actions/contact_merge	Mescla dois contatos

Criar um contato

Campos: inbox_id (obrigatório — associa o contato a um inbox e gera o source_id), name, email, phone_number, identifier, blocked, avatar_url, additional_attributes, custom_attributes.

curl

curl -X POST "https://appchat01.interleads.chat/api/v1/accounts/3/contacts" \
  -H "api_access_token: $INTERLEADS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 5,
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "phone_number": "+5511999998888",
    "custom_attributes": { "origem": "landing-page" }
  }'

Node.js

const res = await fetch(
  "https://appchat01.interleads.chat/api/v1/accounts/3/contacts",
  {
    method: "POST",
    headers: {
      api_access_token: process.env.INTERLEADS_TOKEN,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inbox_id: 5,
      name: "João Silva",
      email: "joao@exemplo.com",
      phone_number: "+5511999998888",
      custom_attributes: { origem: "landing-page" },
    }),
  }
)
const contato = await res.json()

Guarde o source_id

A resposta inclui o contact_inbox criado, com o source_id — é ele que você usa para abrir uma conversa. Para WhatsApp, o source_id costuma ser o número em formato internacional (+55...).

Buscar contatos

curl "https://appchat01.interleads.chat/api/v1/accounts/3/contacts/search?q=joao" \
  -H "api_access_token: $INTERLEADS_TOKEN"

Para condições mais ricas (por atributo, label, data etc.), use POST /contacts/filter com um corpo de filtros.

Atualizar um contato

curl -X PUT "https://appchat01.interleads.chat/api/v1/accounts/3/contacts/456" \
  -H "api_access_token: $INTERLEADS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "custom_attributes": { "plano": "premium" } }'

custom_attributes grava valores em campos que já existem na conta. Aplicar labels a um contato é via POST /contacts/{id}/labels (substitui o conjunto atual). Para criar as labels, veja Labels.

Associar a um inbox

Se precisar tornar um contato existente contatável por outro inbox (gerando um novo source_id):

curl -X POST "https://appchat01.interleads.chat/api/v1/accounts/3/contacts/456/contact_inboxes" \
  -H "api_access_token: $INTERLEADS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "inbox_id": 5, "source_id": "+5511999998888" }'

Erros comuns

Código	Significado
401	Token ausente ou inválido
404	Contato não encontrado
422	Dados inválidos (ex.: telefone/e-mail já em uso, formato inválido)

Referência completa em Códigos de erro.