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âmetro | Tipo | Descrição |
|---|---|---|
page | Integer | A 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. |
after | string | Cursor opaco obtido do meta.next de uma resposta anterior. Retorna o lote de contatos seguinte. Veja Paginação por cursor. |
query | string | Texto 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. |
source | Source | O tipo de integração (ex.: whatsapp) |
tags | string[] | As tags correspondentes, separadas por vírgulas (ex.: sales,lead). As tags são case-insensitive. |
team_uuid | string | O uuid da equipe. |
conversation_state | string | open ou closed. Retorna apenas os contatos cuja conversa está nesse estado. |
last_message_from | string | contact 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_after | string | Uma 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_before | string | Uma 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_user | string | O 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. |
order | string | created_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_types | boolean | Quando 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:
{
"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:
- Faça uma requisição normalmente: cada resposta inclui um token opaco em
meta.next. - Envie o token de volta pelo parâmetro
afterpara obter o próximo lote de contatos. - Continue seguindo
meta.nextaté que ele sejanull— 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 Requestcom a mensagemInvalid pagination cursor. - O parâmetro
pageé ignorado quandoafterestá presente. - Os filtros e a ordem não são codificados no token: envie os mesmos filtros e o mesmo
orderjunto comafterem 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
- Node
- Ruby
- Go
- PHP
- Python
- C#
- Java
- Rust
curl -X GET "https://api.callbell.eu/v1/contacts" \
-H "Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json"
import axios from 'axios';
const response = await axios.get('https://api.callbell.eu/v1/contacts', {
headers: {
'Authorization': 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
'Content-Type': 'application/json'
}
});
require 'net/http'
uri = URI('https://api.callbell.eu/v1/contacts')
req = Net::HTTP::Get.new(uri)
req.content_type = 'application/json'
req['Authorization'] = 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM'
req_options = {
use_ssl: uri.scheme == 'https'
}
res = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(req)
end
package main
import (
"fmt"
"io"
"log"
"net/http"
)
func main() {
client := &http.Client{}
req, err := http.NewRequest("GET", "https://api.callbell.eu/v1/contacts", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM")
req.Header.Set("Content-Type", "application/json")
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
bodyText, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", bodyText)
}
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.callbell.eu/v1/contacts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
'Content-Type: application/json',
]);
$response = curl_exec($ch);
curl_close($ch);
import requests
headers = {
'Authorization': 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
'Content-Type': 'application/json',
}
response = requests.get('https://api.callbell.eu/v1/contacts', headers=headers)
using System.Net.Http;
using System.Net.Http.Headers;
HttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, "https://api.callbell.eu/v1/contacts");
request.Headers.Add("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM");
request.Content = new StringContent("");
request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
HttpResponseMessage response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
string responseBody = await response.Content.ReadAsStringAsync();
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;
class Main {
public static void main(String[] args) throws IOException {
URL url = new URL("https://api.callbell.eu/v1/contacts");
HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
httpConn.setRequestMethod("GET");
httpConn.setRequestProperty("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM");
httpConn.setRequestProperty("Content-Type", "application/json");
InputStream responseStream = httpConn.getResponseCode() / 100 == 2
? httpConn.getInputStream()
: httpConn.getErrorStream();
Scanner s = new Scanner(responseStream).useDelimiter("\\A");
String response = s.hasNext() ? s.next() : "";
System.out.println(response);
}
}
extern crate reqwest;
use reqwest::header;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut headers = header::HeaderMap::new();
headers.insert("Authorization", "Bearer test_gshuPaZoeEG6ovbc8M79w0QyM".parse().unwrap());
headers.insert("Content-Type", "application/json".parse().unwrap());
let client = reqwest::blocking::Client::builder()
.redirect(reqwest::redirect::Policy::none())
.build()
.unwrap();
let res = client.get("https://api.callbell.eu/v1/contacts")
.headers(headers)
.send()?
.text()?;
println!("{}", res);
Ok(())
}
Resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
contacts | Contato[] | Uma lista de contatos. |
meta | object | Metadados 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
{
"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)
{
"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"] }
}
}
]
}