GET /contacts

Liste tous les contacts appartenant au compte. Un filtre peut être spécifié afin d'obtenir des résultats plus précis.

Paramètres optionnels

Paramètre	Type	Description
page	Integer	La page de contacts. Si non spécifiée, la page 1 est utilisée par défaut. Les pages au-delà de 500 ne sont pas disponibles — utilisez plutôt la pagination par curseur.
after	string	Curseur opaque provenant du meta.next d'une réponse précédente. Renvoie le lot de contacts qui le suit. Voir Pagination par curseur.
source	Source	Le type d'intégration (p. ex. whatsapp)
tags	string[]	Les tags correspondants, séparés par des virgules (p. ex. sales,lead). Les tags sont insensibles à la casse.
team_uuid	string	L'uuid de l'équipe.
include_field_types	boolean	Lorsque true, la réponse inclut customFieldsMetadata avec la valeur, le type et les options de chaque champ personnalisé.

Pagination par curseur

La pagination par pages s'arrête à la page 500 (10 000 contacts) : les requêtes au-delà de cette limite renvoient une erreur 400 Bad Request avec le message Pagination limit exceeded. Pour parcourir la liste complète des contacts, utilisez la pagination par curseur :

1. Faites une requête comme d'habitude : chaque réponse inclut un token opaque dans meta.next.
2. Renvoyez ce token via le paramètre after pour récupérer le lot de contacts suivant.
3. Continuez à suivre meta.next jusqu'à ce qu'il vaille null — cela marque le dernier lot.

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

Quelques points à garder à l'esprit :

• Traitez le token comme opaque et renvoyez-le tel quel. Un token malformé renvoie une erreur 400 Bad Request avec le message Invalid pagination cursor.
• Le paramètre page est ignoré lorsque after est présent.
• Les filtres (source, tags, team_uuid) ne sont pas encodés dans le token : envoyez les mêmes filtres avec after à chaque requête.
• Les contacts sont renvoyés dans le même ordre que pour les requêtes par pages (conversation la plus récente en premier). Les contacts créés après le début du parcours ne sont pas inclus.

Exemple de requête

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

Réponse

Paramètre	Type	Description
contacts	Contact[]	Une liste de contacts.
meta	object	Métadonnées de pagination : page et pages pour les requêtes par pages, plus next, le curseur pointant vers le lot suivant (null pour le dernier lot).

Exemple de réponse

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

Exemple de réponse (avec 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"] }
      }
    }
  ]
}