GET /contacts

Lista todos os contatos pertencentes à conta. Um filtro pode ser especificado para obter resultados mais específicos.

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.
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.
include_field_types	boolean	Quando true, a resposta inclui customFieldsMetadata com o valor, tipo e opções de cada campo personalizado.

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 (source, tags, team_uuid) não são codificados no token: envie os mesmos filtros junto com after em cada requisição.
• Os contatos são retornados na mesma ordem das requisições por páginas (conversa mais recente primeiro). Contatos criados após o início do percurso não são incluídos.

Exemplo de requisição

cURL

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

Node

import axios from 'axios';

const response = await axios.get('https://api.callbell.eu/v1/contacts', {
  headers: {
    'Authorization': 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
    'Content-Type': 'application/json'
  }
});

Ruby

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

Go

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

<?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);

Python

import requests

headers = {
    'Authorization': 'Bearer test_gshuPaZoeEG6ovbc8M79w0QyM',
    'Content-Type': 'application/json',
}

response = requests.get('https://api.callbell.eu/v1/contacts', headers=headers)

C#

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();

Java

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);
    }
}

Rust

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

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",
      "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,
      "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"] }
      }
    }
  ]
}