# Konventionen

> Namen, IDs, Zeiten, Telefonnummern, Geld und die Form jeder Antwort. Dieselben Regeln gelten für jeden Aufruf.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/concepts/conventions/

## 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`](https://docs.smartchat.marketing/de/errors/#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`](https://docs.smartchat.marketing/de/errors/#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`:

```json
{
  "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](https://docs.smartchat.marketing/de/concepts/pagination/)):

```json
{ "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](https://docs.smartchat.marketing/de/concepts/errors-overview/).

## 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](https://docs.smartchat.marketing/de/concepts/versioning/)). |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Class` | Dein [Limit](https://docs.smartchat.marketing/de/concepts/rate-limits/). |

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