Pular para o conteúdo principal

GET /contacts

Lista os contatos pertencentes à conta. Por padrão, os contatos são ordenados pela data de criação da conversa, do mais recente para o mais antigo. Os parâmetros opcionais abaixo buscam contatos pelo nome, filtram a lista por atividade da conversa, origem, tags ou equipe, e podem alterar a ordem.

Parâmetros opcionais​

ParâmetroTipoDescrição
pageIntegerA página de contatos. Se não for especificada, o padrão é a página 1. Páginas além da 500 não estão disponíveis — use a paginação por cursor.
afterstringCursor opaco obtido do meta.next de uma resposta anterior. Retorna o lote de contatos seguinte. Veja Paginação por cursor.
querystringTexto a buscar no nome do contato, com até 100 caracteres. A busca ignora maiúsculas, minúsculas e acentos e aceita parte de uma palavra. Veja Buscar pelo nome.
sourceSourceO tipo de integração (ex.: whatsapp)
tagsstring[]As tags correspondentes, separadas por vírgulas (ex.: sales,lead). As tags são case-insensitive.
team_uuidstringO uuid da equipe.
conversation_statestringopen ou closed. Retorna apenas os contatos cuja conversa está nesse estado.
last_message_fromstringcontact retorna os contatos que enviaram a última mensagem da conversa, o que geralmente significa que estão aguardando uma resposta. business retorna os contatos cuja última mensagem foi enviada pela sua conta (um membro da equipe, um bot, uma transmissão ou a API).
last_inbound_message_afterstringUma data e hora ISO 8601, por exemplo 2026-11-12T08:00:00Z. Retorna os contatos cuja mensagem mais recente enviada para você foi recebida nesse horário ou depois. Uma data sem hora (2026-11-12) significa meia-noite UTC. Mensagens enviadas pela sua conta não contam.
last_inbound_message_beforestringUma data e hora ISO 8601. Retorna os contatos cuja mensagem mais recente enviada para você foi recebida nesse horário ou antes. Contatos que nunca enviaram uma mensagem são excluídos sempre que last_inbound_message_after ou last_inbound_message_before estiver definido.
assigned_userstringO e-mail de um membro da equipe, para retornar apenas as conversas atribuídas a essa pessoa, ou unassigned, para retornar apenas as conversas sem nenhum membro da equipe atribuído.
orderstringcreated_at (padrão) ordena pela data de criação da conversa. last_inbound_message_at ordena pelo horário da mensagem mais recente recebida do contato; contatos que nunca enviaram uma mensagem ficam por último. As duas ordens vão do mais recente para o mais antigo.
include_field_typesbooleanQuando true, a resposta inclui customFieldsMetadata com o valor, tipo e opções de cada campo personalizado.

Buscar pelo nome​

query busca no nome do contato. A busca ignora maiúsculas, minúsculas e acentos: hernandez encontra "Hernández". Cada palavra da busca pode corresponder a qualquer parte de uma palavra do nome: riley encontra "Riley Smith", e ey encontra "Reyes". Quando a busca tem várias palavras, todas precisam aparecer no nome, então riley smith encontra "Riley Smith", mas não "Riley Jones". A busca também encontra um nome de usuário do WhatsApp ou um número de telefone que comece com o texto buscado. Para encontrar um contato a partir de um número de telefone completo, use GET /contacts/phone/:phone_number.

query se combina com todos os outros filtros e com os dois modos de paginação. Os resultados mantêm a ordem habitual (a data de criação da conversa, ou a definida por order), e não uma ordem por relevância. Por exemplo, esta requisição lista as conversas abertas dos contatos chamados Riley:

curl -X GET "https://api.callbell.eu/v1/contacts?query=riley&conversation_state=open" \
-H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json"

Uma busca com mais de 100 caracteres retorna um erro 400 Bad Request: {"error": {"query": ["is too long (maximum is 100 characters)"]}}.

Filtrar por atividade da conversa​

Os filtros de conversa podem ser combinados entre si e com source, tags e team_uuid. Por exemplo, esta requisição lista as conversas abertas cuja última mensagem veio do contato, começando pelo contato que escreveu mais recentemente:

curl -X GET "https://api.callbell.eu/v1/contacts?conversation_state=open&last_message_from=contact&order=last_inbound_message_at" \
-H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json"

Para listar quem escreveu para você desde as 8:00 UTC de hoje e não está atribuído a ninguém, use last_inbound_message_after=2026-11-12T08:00:00Z&assigned_user=unassigned.

Os parâmetros last_inbound_message_* e a ordem last_inbound_message_at consideram apenas as mensagens recebidas do contato. Uma resposta da sua equipe não os altera.

Cada contato da resposta inclui lastInboundMessageAt, o horário da mensagem mais recente recebida do contato (null se o contato nunca escreveu), e lastMessageFrom, que vale contact ou business como o parâmetro last_message_from (null se a conversa ainda não tem mensagens). Use-os para conferir os resultados filtrados ou para ver há quanto tempo um contato espera uma resposta.

Um valor não suportado retorna um erro 400 Bad Request que indica cada parâmetro inválido:

response.json
{
"error": {
"conversation_state": ["must be one of: open, closed"],
"assigned_user": ["must be the email of a user inside the account, or unassigned"]
}
}

Paginação por cursor​

A paginação por páginas para na página 500 (10.000 contatos): requisições além desse limite retornam um erro 400 Bad Request com a mensagem Pagination limit exceeded. Para percorrer a lista completa de contatos, use a paginação por cursor:

  1. Faça uma requisição normalmente: cada resposta inclui um token opaco em meta.next.
  2. Envie o token de volta pelo parâmetro after para obter o próximo lote de contatos.
  3. Continue seguindo meta.next até que ele seja null — isso marca o último lote.
curl -X GET "https://api.callbell.eu/v1/contacts?after=eyJ0cyI6MTc1NDM4NDQwMDAwMCwiaWQiOjEyMzQ1fQ" \
-H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json"

Alguns pontos importantes:

  • Trate o token como opaco e envie-o de volta sem alterações. Um token malformado retorna um erro 400 Bad Request com a mensagem Invalid pagination cursor.
  • O parâmetro page é ignorado quando after está presente.
  • Os filtros e a ordem não são codificados no token: envie os mesmos filtros e o mesmo order junto com after em cada requisição.
  • Os contatos são retornados na mesma ordem das requisições por páginas. Contatos criados após o início do percurso não são incluídos. Com order=last_inbound_message_at, um contato que escreve para você durante o percurso passa para o topo da lista, então o percurso pode pular esse contato ou retorná-lo duas vezes.

Exemplo de requisição​

curl -X GET "https://api.callbell.eu/v1/contacts" \
-H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json"

Resposta​

ParâmetroTipoDescrição
contactsContato[]Uma lista de contatos.
metaobjectMetadados de paginação: page e pages para requisições por páginas, além de next, o cursor que aponta para o próximo lote (null no último lote).

Exemplo de resposta​

response.json
{
"contacts": [
{
"uuid": "414a6d692bd645ed803f2e7ce360d4c8",
"name": "John Doe",
"phoneNumber": "+123 456 789",
"avatarUrl": null,
"createdAt": "2020-11-13T21:08:53Z",
"source": "whatsapp",
"href": "https://dash.callbell.eu/contacts/414a6d692bd645ed803f2e7ce360d4c8",
"conversationHref": "https://dash.callbell.eu/chat/f3670b13446b412796238b1cd78899f9",
"assignedUser": "john.doe@email.com",
"lastInboundMessageAt": "2026-11-18T09:12:44Z",
"lastMessageFrom": "contact",
"tags": [
"sales",
"lead"
],
"customFields":{
"Stripe link": "https://stripe.com/contacts/cus1234567",
"Billing Address": "3 Abbey Rd, London"
}
},
...
{
"uuid": "ff8bec9363bc4c29b8b044eabf2afebd",
"name": "Mario Rossi",
"phoneNumber": "+33 11 22 33 44",
"avatarUrl": null,
"createdAt": "2021-02-24T20:33:06Z",
"source": "whatsapp",
"href": "https://dash.callbell.eu/contacts/ff8bec9363bc4c29b8b044eabf2afebd",
"conversationHref": "https://dash.callbell.eu/chat/f3670b13446b412796238b1cd78899f9",
"assignedUser": null,
"lastInboundMessageAt": "2026-11-17T16:40:02Z",
"lastMessageFrom": "business",
"tags": [
"sales",
"lead",
"hot"
],
"customFields":{
"Stripe link": "https://stripe.com/contacts/cus124124153"
}
}
],
"meta": {
"page": 1,
"pages": 42,
"next": "eyJ0cyI6MTc1NDM4NDQwMDAwMCwiaWQiOjEyMzQ1fQ"
}
}

Exemplo de resposta (com include_field_types=true)​

response.json
{
"contacts": [
{
"uuid": "414a6d692bd645ed803f2e7ce360d4c8",
"name": "John Doe",
"customFields": {
"Address": "Oxford Street 123",
"Join Date": "2024-01-15",
"Preferences": "[\"Newsletter\", \"Promotions\"]"
},
"customFieldsMetadata": {
"Address": { "value": "Oxford Street 123", "type": "text" },
"Join Date": { "value": "2024-01-15", "type": "date" },
"Preferences": { "value": ["Newsletter", "Promotions"], "type": "checkbox", "options": ["Newsletter", "Promotions", "Updates"] }
}
}
]
}