Paginação

Os endpoints que listam itens (contatos, mensagens, mensagens agendadas, entregas de webhook…) usam paginação por cursor.

Formato da lista

{
  "object": "list",
  "data": [
    {
      "id": "721bfe94-e549-4354-b90c-a8d679e9b271",
      "object": "contact",
      "name": "João Pereira",
      "phone": "5521987654321",
      "email": null,
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "channel_type": "whatsapp",
      "is_group": false,
      "stage": null,
      "ai_enabled": true,
      "ai_agent_id": null,
      "assigned_to": null,
      "pinned": false,
      "unread_count": 0,
      "last_message_at": "2026-11-11T14:30:12Z",
      "last_message_preview": "Combinado, obrigado!",
      "resolved_at": null,
      "archived_at": null,
      "source": "whatsapp",
      "created_at": "2026-09-14T11:20:00Z",
      "updated_at": "2026-11-11T14:30:12Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xMVQxNDozMDoxMloiLCJpZCI6IjcyMWJmZTk0In0"
}

(Exemplo com limit=1: há mais itens, então has_more é true e next_cursor vem preenchido.)

Campo	Descrição
`object`	Sempre `list`.
`data`	Os itens desta página.
`has_more`	`true` se existem mais itens depois desta página.
`next_cursor`	Valor para buscar a próxima página, ou `null` na última.

Parâmetros

Parâmetro	Tipo	Descrição
`limit`	inteiro	Itens por página, de 1 a 100. Padrão: 20.
`cursor`	string	O `next_cursor` da página anterior.

O cursor é opaco: não tente montar nem interpretar o valor, só repasse o que a API devolveu. Mantenha os mesmos filtros (ex.: search, stage_id) ao pedir a próxima página.

Percorrer todas as páginas

async function listarTodosOsContatos() {
  const contatos = [];
  let cursor = null;

  do {
    const url = new URL('https://platform.toptalking.com.br/v1/contacts');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
    });
    const page = await res.json();
    if (!res.ok) throw new Error(page.error.message);

    contatos.push(...page.data);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return contatos;
}

import os
import requests

def listar_todos_os_contatos():
    contatos, cursor = [], None
    headers = {"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"}
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "https://platform.toptalking.com.br/v1/contacts",
            headers=headers, params=params, timeout=30,
        )
        res.raise_for_status()
        page = res.json()
        contatos.extend(page["data"])
        if not page["has_more"]:
            return contatos
        cursor = page["next_cursor"]

# Primeira página
curl "https://platform.toptalking.com.br/v1/contacts?limit=100" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

# Próxima página: passe o next_cursor recebido
curl "https://platform.toptalking.com.br/v1/contacts?limit=100&cursor=eyJ0IjoiMjAyNi0xMS0xMVQxNDozMDoxMloiLCJpZCI6IjcyMWJmZTk0In0" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"