Seiten, Filter und Sortierung

Jede Liste in der API funktioniert gleich. Listen geben nie alles auf einmal zurück.

#Seiten

Die Antwort sagt dir, ob es mehr gibt:

{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0yNVQwOTo0MTowN1oiLCJpIjoiLi4uIn0",
  "url": "/v1/contacts"
}

Die Python-Beispiele nutzen das Paket requests (pip install requests). Um alles zu lesen, wiederhole den Aufruf mit cursor gleich next_cursor, bis has_more den Wert false hat:

import os
import requests

url = "https://api.smartchat.marketing/v1/contacts"
headers = {"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]}
params = {"limit": 100}
while True:
    page = requests.get(url, headers=headers, params=params).json()
    for item in page["data"]:
        print(item["id"])
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]

const headers = { Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}` };
let cursor: string | null = null;
do {
  const query = new URLSearchParams({ limit: "100", ...(cursor ? { cursor } : {}) });
  const page = await (await fetch(`https://api.smartchat.marketing/v1/contacts?${query}`, { headers })).json();
  for (const item of page.data) console.log(item.id);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

#Der Cursor

• Der Cursor ist ein undurchsichtiger Text. Lies ihn nicht und baue ihn nicht selbst.
• Er funktioniert nur mit den gleichen Filtern und für das gleiche Konto. Mit anderen Filtern lautet die Antwort invalid_cursor. Fang ohne Cursor neu an.
• Die Reihenfolge ist stabil: Neue Einträge, die beim Blättern auftauchen, lassen dich keine Einträge verpassen oder doppelt sehen.

#Filter

Filter sind Query-Parameter, die wie das Feld heißen, zum Beispiel tag= oder optin_whatsapp=. Jede Listenseite in der API-Referenz zeigt ihre Filter im Abschnitt "Listen, Filter und Sortierung". Ein unbekannter Filter ergibt unknown_parameter; er wird nie still ignoriert.

#Sortierung

Die Standard-Reihenfolge ist neueste zuerst (created_at absteigend, dann id absteigend). Eine Liste, die sich anders sortieren lässt, sagt das auf ihrer Referenzseite und akzeptiert order_by.

#Die eine Ausnahme: Wissenssuche

GET /knowledge/search (MCP: search_knowledge) ist eine Suche, keine Liste. Sie gibt nur die besten Textstellen zurück: limit ist 1 bis 12 (Standard 5) und es gibt keinen cursor. Um die Dokumente selbst zu lesen, nutze die normale Liste GET /knowledge-documents.

#Summen

Die meisten Listen haben keine Summe. Wo total_count existiert, ist er ungefähr und kann ein wenig danebenliegen.