Konventionen

#Namen

Alles ist Englisch. Felder, Parameter, Werte, Fehlercodes, Ereignisnamen und Werkzeugnamen nutzen snake_case (Ereignisse nutzen resource.event, zum Beispiel contact.created).
Pfade sind klein geschrieben, mit Bindestrichen und Nomen im Plural, zum Beispiel /contacts und /webhook-endpoints. Ein Pfad mit einem einzigen Objekt pro Konto steht im Singular, zum Beispiel /landing-page.
Aktionen sind Unterpfade mit einem Verb, zum Beispiel /contacts/{contact_id}/unsubscribe.

#IDs

Jede ID hat ein Präfix, das dir die Art des Objekts verrät. Sendest du eine ID der falschen Art, lautet die Antwort validation_failed, nicht "nicht gefunden".

Object	ID starts with	Example
Contact	`con_`	`con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Conversation	`cnv_`	`cnv_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Send	`snd_`	`snd_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Template	`tpl_`	`tpl_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Newsletter	`nwl_`	`nwl_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Automation	`aut_`	`aut_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Automation run	`run_`	`run_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Follow-up sequence	`fup_`	`fup_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Follow-up step	`stp_`	`stp_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Learned answer	`ans_`	`ans_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Knowledge document	`doc_`	`doc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Media file	`med_`	`med_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Webhook endpoint	`whe_`	`whe_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Webhook delivery	`whd_`	`whd_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Event	`evt_`	`evt_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Preview plan	`pln_`	`pln_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Contact export	`exp_`	`exp_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
API key	`key_`	`key_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`
Account	`acc_`	`acc_0f8c1a2e4b7d4c3e9a5b6d7e8f901234`

Objekte anderer Konten sehen genauso aus wie Objekte, die es nicht gibt: Du bekommst immer die Antwort "nicht gefunden". Das ist Absicht.

#Zeiten, Telefonnummern, Geld

Zeiten sind ISO 8601 in UTC mit Z, zum Beispiel 2026-10-25T09:41:07Z. Ereignisse haben Millisekunden. Feldnamen enden auf _at für einen Zeitpunkt und auf _on für ein Datum (YYYY-MM-DD). Du darfst eine Zeit mit Versatz wie +01:00 senden; du bekommst UTC zurück.
Telefonnummern nutzen das Format E.164, zum Beispiel +4915112345678. Eine ungültige Nummer ergibt invalid_phone_number.
Geld ist eine ganze Zahl in der kleinsten Einheit plus currency in Kleinbuchstaben (eur). Credits sind ganze Zahlen. Für Geld gibt es keine Kommazahlen.
Boolesche Werte sind true und false. Ein Wert, der nicht gesetzt ist, ist null, nie "".

#Feste Werte

Field	Values	Meaning
optin_whatsapp	`none`, `pending`, `confirmed`, `opted_out`	WhatsApp opt-in state of a contact.
send status	`queued`, `sent`, `delivered`, `read`, `failed`, `skipped`	State of a single send.
template status	`draft`, `pending`, `approved`, `rejected`, `paused`	State of a message template.
newsletter status	`draft`, `scheduled`, `sending`, `paused`, `completed`, `canceled`, `failed`	State of a newsletter.
automation status	`draft`, `active`, `paused`	State of an automation. A new automation without a status is a draft.
conversation status	`open`, `closed`	State of a conversation.
acquisition	`landing_page`, `import`, `api`, `manual`, `automation`, `service`	Where a contact came from.
contact status (`status`)	`confirmed`, `unconfirmed`, `opted_out`, `automation`, `support`	Kind of a contact. `confirmed` and `unconfirmed` say if the opt-in is done, `opted_out` is a contact who unsubscribed.
purpose	`marketing`, `automation`, `service`	Why a contact was created: for marketing, for an automation or for service messages.
tag origin (`origin`)	`system`, `manual`, `ai`	Who set a tag: the system, a person, or the AI.

#Die Form einer Antwort

Ein Objekt kommt flach zurück, mit object (die Art) und id:

{
  "object": "contact",
  "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "name": "Mia Muster",
  "phone": "+4915112345678",
  "email": null,
  "tags": ["regular customer"],
  "optin_whatsapp": "confirmed",
  "created_at": "2026-10-25T09:41:07Z"
}

Eine Liste packt Objekte in data (Seiten):

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

Es gibt kein Feld ok oder success. Erfolg ist der HTTP-Status; ein Problem ist ein Fehler.

#Header bei jeder Antwort

Header	Bedeutung
`Request-Id`	ID dieser Anfrage (`req_...`). Gib sie dem Support.
`SmartChat-Version`	Version der API, die geantwortet hat (Versionen).
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Class`	Dein Limit.

Neue Felder können jederzeit in Antworten erscheinen. Ignoriere Felder, die du nicht kennst.