Listar contatos

Liste os contatos de um número, com filtros e paginação por cursor. Os itens vêm do atualizado mais recentemente para o mais antigo.

Cada contato pertence a um número: {ref} é main (número principal), o alias de um número extra ou o id dele (num_…), e o mesmo telefone alcançado por dois números diferentes corresponde a dois contatos distintos.

Endpoint

GET /v1/contacts?limit=20&cursor=<opaque>

Para números extras: GET /v1/numbers/{ref}/contacts?limit=20&cursor=<opaque>

Usando números extras?

Para listar contatos de um número extra, use /v1/numbers/{ref}/contacts, onde {ref} é o alias do seu número extra (ou o id dele, num_…). Saiba mais.

Escopo obrigatório: contacts:read.

Parâmetros de consulta

Parâmetro	Tipo	Descrição
limit	int	1 a 200 (padrão 50)
cursor	string	Token opaco retornado em cursor
phone	string	Filtro exato por telefone E.164. Na URL, escreva o + como %2B (phone=%2B5511988887777) ou envie só os dígitos (phone=5511988887777): um + solto vira espaço e o filtro não encontra nada
name	string	Correspondência parcial sobre o nome do contato
source	enum	inbound | outbound | self | mention: mention é o contato observado pela primeira vez por ter sido mencionado em uma mensagem; contatos criados por menção não ocupam a cota de contatos
contacted_in_cycle	bool	Retorna apenas os contatos com quem você falou pelo Turbo Notify dentro do ciclo de faturamento atual (novos ou recorrentes). Um envio que não chegou ao WhatsApp não conta

Exemplo de request

cURL

curl -X GET "https://api.turbonotify.com/v1/contacts?limit=20" \
  -H "Authorization: Bearer SUA_CHAVE"

Só os contatos que ocuparam a cota do ciclo atual:

curl -X GET "https://api.turbonotify.com/v1/contacts?contacted_in_cycle=true" \
  -H "Authorization: Bearer SUA_CHAVE"

Node

const res = await fetch("https://api.turbonotify.com/v1/contacts?limit=20", {
  headers: { Authorization: "Bearer SUA_CHAVE" },
});
const { data, cursor, has_more } = await res.json();

Python

import httpx
r = httpx.get(
    "https://api.turbonotify.com/v1/contacts",
    params={"limit": 20},
    headers={"Authorization": "Bearer SUA_CHAVE"},
)
data = r.json()

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest(
        "GET",
        "https://api.turbonotify.com/v1/contacts?limit=20",
        nil,
    )
    req.Header.Set("Authorization", "Bearer SUA_CHAVE")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

PHP

<?php
$url = 'https://api.turbonotify.com/v1/contacts?limit=20';

$options = [
    'http' => [
        'header' => ['Authorization: Bearer SUA_CHAVE'],
        'method' => 'GET'
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
var_dump($response['data']);
?>

C#

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer SUA_CHAVE");

var response = await client.GetAsync(
    "https://api.turbonotify.com/v1/contacts?limit=20"
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Java

import java.net.http.*;
import java.net.URI;

public class ListarContatos {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newHttpClient();

        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.turbonotify.com/v1/contacts?limit=20"))
            .header("Authorization", "Bearer SUA_CHAVE")
            .GET()
            .build();

        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Resposta (200)

Status HTTP: 200

{
  "data": [
    {
      "id": "ct_a1b2c3d4e5f6789012345678901234ab",
      "number_alias": "main",
      "phone_number": "+5511988887777",
      "name": "João Silva",
      "is_self": false,
      "first_messaged_at": "2026-05-10T13:25:00Z",
      "last_interaction_at": "2026-05-10T13:42:00Z",
      "verified_on_whatsapp_at": "2026-05-10T13:25:00Z",
      "picture": {
        "kind": "unavailable",
        "reason": "peer_has_none"
      },
      "refresh": null,
      "created_at": "2026-05-10T13:25:00Z",
      "updated_at": "2026-05-10T13:42:00Z"
    }
  ],
  "cursor": "eyJpZCI6ImN0XzAxIn0=",
  "has_more": true
}

Cada item é o mesmo objeto retornado por Detalhe, que explica cada campo. O phone_number é o E.164 completo (sem máscara). O contato tem as suas próprias datas (created_at, updated_at, first_messaged_at e as demais), que não repetem as datas de um evento.

Veja também: Detalhe · Erros.