# Nachrichten & Konversationen

Mit der Messages API können Sie Nachrichten an jeden Kontakt senden, Konversationen nachlesen, bereits gesendete Nachrichten korrigieren oder entfernen, auf Nachrichten reagieren, vollständige Chat-Verläufe abrufen, Transkripte exportieren und Chats als gelesen oder ungelesen markieren – alles, ohne den Posteingang zu öffnen.

Alle Pfade auf dieser Seite beziehen sich auf die Basis-URL `https://api.youraiconnector.com/v1`. Jede Anfrage erfordert Ihren API-Schlüssel – siehe [Authentifizierung](authentication.md) für die vollständige Liste der Möglichkeiten, diesen zu senden. Die folgenden Beispiele verwenden den Header `X-API-Key`, wobei ein cURL-Beispiel auch das Abfrageformular `?apiKey=` zeigt.

> **Wie die Zustellung funktioniert:** Das Senden einer Nachricht wartet **nicht** auf deren Ankunft. Die API nimmt Ihre Nachricht entgegen, antwortet sofort mit einer Nachrichten-ID und stellt sie dann im Hintergrund über den Kanal des Kontakts (WhatsApp, SMS, Instagram usw.) zu. Um nachzuverfolgen, ob eine Nachricht tatsächlich zugestellt oder gelesen wurde, sollten Sie auf Status-Updates via [Webhooks](webhooks.md) hören – verwenden Sie kein Polling. Die Antwort auf das Senden bestätigt lediglich, dass die Nachricht akzeptiert wurde.

---

## Nachricht senden

Es gibt zwei Möglichkeiten zum Senden. Wählen Sie diejenige, die am besten dazu passt, wie Sie den Kontakt bereits identifizieren:

- **Senden per Kontakt-ID** — Sie kennen die ID des Kontakts bereits (z. B. weil Sie den Kontakt über die API erstellt oder über einen Webhook erhalten haben). Verwenden Sie `POST /contacts/{contactId}/send-message`.
- **Senden per Kontaktidentität** — Sie kennen die Telefonnummer, Instagram-ID usw. des Kontakts, aber nicht dessen interne ID. Verwenden Sie `POST /contacts/send` und lassen Sie die Plattform den richtigen Kontakt finden.

Beide Methoden stellen die Nachricht auf die gleiche Weise in die Warteschlange und liefern sie über den Kanal aus, den der Kontakt nutzt. Sie wählen keinen Transportweg – die Plattform leitet WhatsApp-Kontakte über WhatsApp, SMS-Kontakte über SMS usw. weiter.

### Senden per Kontakt-ID

`POST /contacts/{contactId}/send-message`

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `body` | Ja | Der zu sendende Nachrichtentext. |
| `mediaUrl` | Nein | URL einer Mediendatei (Bild, Dokument usw.), die angehängt werden soll. |
| `mediaContentType` | Nein | MIME-Typ der angehängten Medien, z. B. `image/jpeg`. |
| `pauseBot` | Nein | `true` pausiert die KI für diesen Kontakt, während die Nachricht gesendet wird – für die Übernahme durch einen Menschen. Siehe [KI pausieren oder fortsetzen](#pause-or-resume-the-ai-for-one-contact). |
| `clearIncompleteReply` | Nein | `true` verwirft eine halbfertige Bot-Antwort, damit diese nach Ihrer Nachricht nicht fortgesetzt wird. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi! Your appointment is confirmed for tomorrow at 10:00.",
    }),
  }
);
const data = await res.json();
console.log(data.messageId);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}
```

### Senden per Kontaktidentität

`POST /contacts/send`

Verwenden Sie dies, wenn Sie die interne ID des Kontakts nicht haben. Geben Sie den Nachrichten-`body` sowie **entweder** eine `contact_id` **oder** ein `channel` zusammen mit dem Identitätsfeld an, das zu diesem Kanal passt.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `body` | Ja | Der zu sendende Nachrichtentext. |
| `contact_id` | Nein | ID eines bestehenden Kontakts. Wenn gesetzt, werden die Identitätsfelder unten nicht benötigt. |
| `channel` | Nein | Kanal, über den gesendet werden soll. Erforderlich, wenn `contact_id` nicht angegeben ist. Einer der 14 für ausgehende Nachrichten verfügbaren Kanäle: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `instagram_private`, `messenger`, `telegram`, `chat-widget`, `custom`, `email`, `line`, `imessage`, `linkedin`, `viber`. |
| `phone_number` | Nein | Telefonnummer des Kontakts im internationalen Format. Wird mit `whatsapp`, `whatsapp_web` und `sms` verwendet. |
| `instagram_id` | Nein | Instagram-Benutzer-ID des Kontakts. Wird mit `instagram` verwendet. |
| `messenger_id` | Nein | Messenger-Benutzer-ID des Kontakts. Wird mit `messenger` verwendet. |
| `telegram_user_id` | Nein | Telegram-Benutzer-ID des Kontakts. Wird mit `telegram` verwendet. |
| `media_url` | Nein | URL einer Mediendatei zum Anhängen. |
| `media_content_type` | Nein | MIME-Typ der angehängten Medien, z. B. `image/jpeg`. |

**Welche Kanäle können über eine Identität aufgelöst werden.** Nur sechs der 14 Kanäle akzeptieren ein Identitätsfeld anstelle einer `contact_id`: `whatsapp`, `whatsapp_web` und `sms` werden über `phone_number` nachgeschlagen, `instagram` über `instagram_id`, `messenger` über `messenger_id` und `telegram` über `telegram_user_id`. Die anderen acht — `instagram_private`, `chat-widget`, `custom`, `email`, `line`, `imessage`, `linkedin` und `viber` — haben keine öffentliche Identität, die nachgeschlagen werden kann, daher erfordert das Senden über diese Kanäle `contact_id`; die alleinige Übergabe von `channel` führt zu einem `400`, der besagt, dass `contact_id` erforderlich ist.

**cURL** (unter Verwendung des Abfrageformulars `?apiKey=`)

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])
```

**Antwort** (`201 Created`):

```json
{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}
```

> **Warum eine Nachricht abgelehnt werden könnte:** Ein Kontakt, bei dem „Nicht stören“ oder der Privatmodus aktiviert ist, kann keine ausgehenden Nachrichten empfangen — die Anfrage schlägt mit einem `422` fehl. Wenn kein Kontakt mit der von Ihnen angegebenen ID oder Identität übereinstimmt, erhalten Sie ein `404`.

---

## Nachrichten eines Kontakts auflisten

`GET /contacts/{contactId}/messages`

Gibt die Nachrichten eines Kontakts zurück, beginnend mit der neuesten, mit cursorbasierter Paginierung.

| Abfrageparameter | Erforderlich | Beschreibung |
|---|---|---|
| `limit` | Nein | Seitengröße. Standard `50`, Maximum `100`. |
| `cursor` | Nein | Der `next_cursor`-Wert aus einer vorherigen Antwort. Gibt Nachrichten zurück, die älter als der Cursor sind. |
| `filter` | Nein | Nach Inhaltstyp filtern: `all` (Standard), `text`, `media` oder `tool_use`. |
| `direction` | Nein | Nach Richtung filtern: `all` (Standard), `inbound` (vom Kontakt empfangen) oder `outbound` (von Ihnen gesendet). |

> **Hinweis zu Filtern und Paginierung:** Die Filter `filter` und `direction` werden auf jede Seite angewendet, nachdem sie gelesen wurde. Daher kann eine gefilterte Seite weniger Elemente enthalten als `limit`. Der `next_cursor` schreitet weiterhin durch die gesamte Konversation voran, fahren Sie also mit der Paginierung fort, bis `next_cursor` den Wert `null` hat.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}
```

### Nachrichtenfelder

| Feld | Beschreibung |
|---|---|
| `id` | Eindeutige ID der Nachricht. |
| `body` | Textinhalt der Nachricht. |
| `direction` | `inbound` (vom Kontakt empfangen) oder `outbound` (von Ihrem Konto gesendet). |
| `channel` | Kanal, über den die Nachricht gesendet oder empfangen wurde (z. B. `whatsapp`, `sms`, `instagram`). |
| `status` | Aktueller Zustellstatus, z. B. `Created`, `sent`, `delivered`, `read`, `failed`. |
| `type` | Nachrichtentyp. Nur-Text-Nachrichten haben den Typ `null`; automatisierte Aktivitäten von Assistenten-Tools sind als `tool_use` gekennzeichnet. |
| `timestamp` | ISO 8601-Zeitpunkt der Erstellung der Nachricht. |
| `media_url` | URL einer angehängten Mediendatei, falls vorhanden. |
| `media_content_type` | MIME-Typ der angehängten Medien, falls vorhanden. |
| `bot_reply` | `true`, wenn die Nachricht vom KI-Assistenten generiert wurde. |
| `score` | Ihre Bewertung der Nachricht: `1` Daumen hoch, `-1` Daumen runter, `0` wenn sie nicht bewertet wurde. Siehe [Nachricht bewerten oder mit Stern markieren](#rate-or-star-a-message). |
| `is_important` | `true`, wenn die Nachricht mit einem Stern markiert wurde. |
| `is_deleted` | `true`, wenn die Nachricht gelöscht wurde. Gelöschte Nachrichten verbleiben in der Liste, aber ihre Felder `body` und `media_url` sind leer. |
| `reactions` | Emoji-Reaktionen auf die Nachricht von beiden Seiten. Immer ein Array – leer, wenn keine vorhanden sind. Jeder Eintrag enthält `emoji`, `from_phone_number`, `from_me` (`true`, wenn die Reaktion von Ihnen stammt) und `reacted_at`. |

---

## Chat-Sitzungen auflisten

Eine Chat-Sitzung ist ein Konversationsfenster mit einem Kontakt: Es öffnet sich, wenn dieser zu schreiben beginnt, und schließt sich, wenn das Gespräch beendet ist. Sitzungen ermöglichen es Ihnen, einen langen Verlauf in lesbare Konversationen zu unterteilen, anstatt eine endlose Liste zu erhalten.

### Aktuelle Sitzungen über alle Kontakte hinweg

`GET /chat-sessions/recent`

Gibt die Sitzungen zurück, die in den letzten X Stunden begonnen haben, sortiert nach Aktualität, über alle Kontakte des Kontos hinweg.

| Abfrageparameter | Erforderlich | Beschreibung |
|---|---|---|
| `hours` | Ja | Wie viele Stunden zurückgeblickt werden soll. Muss eine positive ganze Zahl sein. |
| `status` | Nein | Nur Sitzungen mit diesem Status zurückgeben: `ChatSessionOpened` oder `ChatSessionClosed`. |
| `limit` | Nein | Maximale Anzahl der zurückzugebenden Sitzungen. Standard `100`, Maximum `100`. |
| `includeMessages` | Nein | `true` fügt jeder Sitzung ein `messages`-Array hinzu. Standardmäßig deaktiviert, da dies die Antwort deutlich vergrößert. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}
```

### Alle Sitzungen für einen Kontakt

`GET /chat-sessions/{contactId}`

Gibt jede Chat-Sitzung für einen einzelnen Kontakt zurück. Gleiche Parameter wie `status`, `limit` und `includeMessages` wie oben – `hours` findet hier keine Anwendung.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}
```

> **Die Feldnamen für die Sitzungs-ID unterscheiden sich zwischen den beiden Endpunkten.** Die Liste der aktuellen Sitzungen nennt sie `session_id` (sie enthält auch die Details des Kontakts, da Sitzungen von vielen Kontakten stammen); die Liste pro Kontakt nennt sie `id`. Beide Werte können als `{sessionId}` verwendet werden, wenn Sie den vollständigen Thread wie unten beschrieben abrufen.

Wenn `includeMessages=true` gesetzt ist, erhält jede Sitzung ein `messages`-Array, dessen Einträge `id`, `body`, `direction`, `timestamp`, `type`, `channel` und `status` enthalten.

---

## Chat-Sitzungs-Thread abrufen

`GET /contacts/{contactId}/chat-sessions/{sessionId}/messages`

Eine Chat-Sitzung gruppiert die Nachrichten eines Kontakts in einem Konversationsfenster. Dieser Endpunkt gibt den vollständigen Thread einer einzelnen Sitzung zurück, **beginnend mit der ältesten Nachricht**, zusammen mit den Metadaten der Sitzung. Sie finden Sitzungs-IDs für einen Kontakt über die Chat-Sitzungs-Endpunkte.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}
```

Das `session`-Objekt meldet `status` (`ChatSessionOpened` während der Aktivität, `ChatSessionClosed` nach Beendigung), `start_date_time`, `end_date_time` und einen für Menschen lesbaren `tag`. Das `messages`-Array verwendet dieselben [Nachrichtenfelder](#message-fields) wie der Listen-Endpunkt.

---

## Nachrichten bearbeiten, löschen und darauf reagieren

Diese Endpunkte ändern eine Nachricht, nachdem sie gesendet wurde. Zwei davon greifen sowohl auf den Kanal des Kontakts als auch auf Ihre eigene Kopie zu. Lesen Sie daher die Einleitung des Abschnitts, bevor Sie diese implementieren – was möglich ist, hängt vollständig vom Kanal ab, auf dem die Konversation stattfindet.

**Was jeder Kanal ermöglicht**

| Aktion | Kanäle, die die Kopie des Kontakts ändern können | Zeitlimit |
|---|---|---|
| Gesendete Nachricht bearbeiten | Chat-Widget, WhatsApp Web, Telegram, LinkedIn | Kein Limit beim Chat-Widget, 15 Minuten bei WhatsApp Web, 48 Stunden bei Telegram, 60 Minuten bei LinkedIn |
| Für alle löschen | Chat-Widget, WhatsApp Web, Telegram, LinkedIn | 60 Minuten bei LinkedIn; die anderen haben kein veröffentlichtes Limit |
| Mit einem Emoji reagieren | WhatsApp Web, Telegram | Keines |

Bei allen anderen Kanälen — WhatsApp Business API, SMS, Instagram, Messenger, E-Mail, LINE, benutzerdefinierte Kanäle — entfernt ein Löschvorgang die Nachricht zwar aus Ihrem Posteingang, der Kontakt behält jedoch seine Kopie, und das Bearbeiten oder Reagieren ist überhaupt nicht möglich.

### Nachricht bearbeiten

`POST /contacts/{contactId}/messages/{messageId}/edit`

Schreibt eine bereits gesendete Nachricht auf dem Gerät des Kontakts und in Ihrer Kopie um.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `body` | Ja | Der neue Nachrichtentext. Darf nicht leer sein und darf maximal 4096 Zeichen lang sein. |

Im Gegensatz zum Löschen **schlägt dies deutlich fehl**, wenn der Kanal dies verweigert: Sie erhalten einen `409` und Ihre Kopie bleibt exakt so, wie der Kontakt sie hat, da das Anzeigen einer Bearbeitung, die er nie erhalten hat, zu einer Diskrepanz zwischen beiden Seiten führen würde. Das Feld `edit_reason` gibt an, warum — das Bearbeitungsfenster des Kanals ist abgelaufen, der Kanal ist getrennt oder etwas anderes ist schiefgelaufen.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}
```

Wenn der Kanal die Bearbeitung nicht akzeptiert, erhalten Sie stattdessen einen `409` und es wurde nichts geändert:

```json
{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}
```

Eine Nachricht, die bereits gelöscht wurde, ein Kanal, der überhaupt nicht bearbeiten kann, und eine Nachricht, die für ihren Kanal zu alt ist, geben alle `400` zurück — die Anfrage erreicht den Kanal nie.

### Eine Nachricht löschen

`DELETE /contacts/{contactId}/messages/{messageId}`

Entfernt die Nachricht aus Ihrer Unterhaltung und zieht, sofern der Kanal dies zulässt, auch die Kopie des Kontakts zurück. Kein Request-Body.

Dies antwortet immer mit `200`, wenn die Nachricht existierte, selbst wenn die Kopie des Kontakts nicht zurückgezogen werden konnte — Ihre Kopie **ist** weg, daher wäre ein Fehler irreführend. Lesen Sie die drei Felder in der Antwort, um dem Benutzer mitzuteilen, was tatsächlich passiert ist:

| Feld | Beschreibung |
|---|---|
| `revoke_supported` | Ob dieser Kanal Nachrichten überhaupt zurückziehen kann. |
| `revoked` | Ob die Kopie auf dem Gerät des Kontakts entfernt wurde. |
| `revoke_reason` | Warum sie nicht entfernt wurde, wenn `revoked` den Wert `false` hat — zum Beispiel `revoke_window_closed` oder `already_deleted`. |

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}
```

> Gelöschte Nachrichten werden nicht aus dem Konversationsverlauf entfernt. Sie verbleiben in `GET /contacts/{contactId}/messages` mit `is_deleted: true` sowie einem leeren `body` und `media_url`.

### Mehrere Nachrichten gleichzeitig löschen

`POST /contacts/{contactId}/messages/bulk-delete`

Löscht eine Reihe von Nachrichten nur auf Ihrer Seite. Die Nachrichtentexte und Anhänge werden geleert, aber **auf dem Gerät des Kontakts wird nichts zurückgezogen** – um eine Nachricht auch dort zu entfernen, löschen Sie sie einzeln über den oben genannten Endpunkt für einzelne Nachrichten.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `message_ids` | Ja | Ein nicht leeres Array von Nachrichten-IDs, bis zu 500 pro Anfrage. `messageIds` wird als Alias akzeptiert. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "deleted": 2
}
```

### Auf eine Nachricht reagieren

`POST /contacts/{contactId}/messages/{messageId}/react`

Fügt Ihre eigene Emoji-Reaktion zu einer Nachricht hinzu oder nimmt sie durch Senden eines leeren Strings wieder zurück. Die Reaktionen des Kontakts selbst werden niemals angetastet.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `emoji` | Ja | Das Emoji für die Reaktion oder `""`, um Ihre Reaktion zu entfernen. Muss ein einzelner String ohne Leerzeichen mit maximal 16 Zeichen sein. |

Wie bei der Bearbeitung schlägt dies fehl, anstatt eine Reaktion anzuzeigen, die der Kontakt nie erhalten hat. Der Fehler gibt an, ob ein erneuter Versuch sinnvoll ist:

- `422` — kann in dieser Konversation niemals zugestellt werden: Der Kanal unterstützt keine Reaktionen, die Nachricht hat keine kanalinterne ID oder das Emoji liegt außerhalb des vom Kanal erlaubten Satzes.
- `409` — der Kanal war vorübergehend nicht erreichbar. Ein erneuter Versuch könnte funktionieren.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}
```

Das `reactions`-Array ist der vollständige Satz der aktuell auf der Nachricht vorhandenen Reaktionen, sowohl Ihre als auch die des Kontakts. Bei einem `409` oder `422` wird es unverändert zurückgegeben, sodass ein Client, der direkt daraus rendert, niemals eine Reaktion anzeigt, die nicht zugestellt wurde.

### Eine Nachricht bewerten oder mit einem Stern markieren

`PATCH /contacts/{contactId}/messages/{messageId}`

Bewertet eine Nachricht mit „Daumen hoch“ oder „Daumen runter“ und/oder markiert sie als wichtig. Dies dient nur Ihrer eigenen Buchführung – es wird nichts an den Kontakt gesendet.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `score` | Nein | `1` Daumen hoch, `-1` Daumen runter, `0` löscht die Bewertung. |
| `is_important` | Nein | `true` markiert die Nachricht mit einem Stern, `false` entfernt den Stern wieder. Muss ein echter boolescher Wert sein, nicht der String `"true"`. |

Senden Sie mindestens eines der beiden, sonst erhalten Sie einen `400`. Nur das, was Sie senden, wird geschrieben. Das Markieren einer Nachricht mit einem Stern löscht also niemals deren Bewertung und umgekehrt – und die Antwort spiegelt nur die Felder wider, die Sie gesendet haben.

**cURL**

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});
```

**Python**

```python
import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}
```

---

## Nachrichten als gelesen markieren

Sie können den Status „ungelesen“ entweder für bestimmte Nachrichten oder für die gesamte Konversation löschen.

### Bestimmte Nachrichten als gelesen markieren

`POST /contacts/{contactId}/messages/mark-read`

Übergeben Sie die IDs der Nachrichten, die als gelesen markiert werden sollen.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `message_ids` | Ja | Ein nicht leeres Array von Nachrichten-IDs (bis zu 500 pro Anfrage). |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}
```

### Den gesamten Chat als gelesen markieren

`POST /contacts/{contactId}/mark-read`

Löscht das „Ungelesen“-Symbol für die gesamte Konversation des Kontakts im Posteingang. Es ist kein Anfragetext erforderlich.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123"
}
```

### Den gesamten Chat als ungelesen markieren

`POST /contacts/{contactId}/mark-unread`

Setzt das Badge für ungelesene Nachrichten zurück auf die Unterhaltung – praktisch, wenn jemand aus Ihrem Team einen Chat geöffnet hat, ihn aber wieder zurückgibt. Es ist kein Request-Body erforderlich.

Dies ist ein reines Posteingangs-Flag: Es ändert **nicht**, wann die Unterhaltung zuletzt gelesen wurde, daher wird bei Kanälen, die dies unterstützen, keine Lesebestätigung an den Kontakt gesendet.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "contact_id": "contact123"
}
```

---

## Eine Unterhaltung exportieren

Exporte liefern Ihnen eine ganze Unterhaltung als lesbares Transkript, anstatt durch Nachrichten blättern zu müssen. Jeder Export-Endpunkt akzeptiert einen `filter` von `all` (Standard), `text`, `media` oder `tool_use`, passend zum Filter in der Nachrichtenliste.

### Chat eines Kontakts exportieren

`GET /chat-exports/{contactId}`

| Abfrageparameter | Erforderlich | Beschreibung |
|---|---|---|
| `format` | Nein | `txt` (Standard) gibt einen Download-Link zu einem Klartext-Transkript zurück. `json` gibt die Nachrichten als strukturierte Daten in der Antwort zurück. |
| `filter` | Nein | `all` (Standard), `text`, `media` oder `tool_use`. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])
```

**Antwort mit `format=json`** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}
```

Bei `format=txt` (dem Standard) ist `data` stattdessen ein Download-Link zur generierten Transkript-Datei:

```json
{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}
```

> **Der Download-Link ist nur kurzzeitig gültig.** Laden Sie die Datei herunter, sobald Sie den Link erhalten, anstatt ihn zu speichern – fordern Sie einen neuen Export an, wenn Sie das Transkript erneut benötigen.

### Alle kürzlichen Unterhaltungen exportieren

`GET /chat-exports/recent`

Exportiert die Konversationen aller Kontakte, die in den letzten X Stunden aktiv waren, in einem einzigen Aufruf.

| Abfrageparameter | Erforderlich | Beschreibung |
|---|---|---|
| `hours` | Ja | Wie viele Stunden Aktivität zurückverfolgt werden sollen. Muss eine positive ganze Zahl sein. |
| `format` | Nein | `json` (Standard) gibt einen Eintrag pro Kontakt zurück. `txt` gibt eine einzelne herunterladbare Textdatei mit allen Konversationen darin zurück. |
| `limit` | Nein | Maximale Anzahl der zu exportierenden Kontakte. Standard `50`, Maximum `100`. |
| `filter` | Nein | `all` (Standard), `text`, `media` oder `tool_use`. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}
```

Bei `format=txt` ist die Antwort die Textdatei selbst, die als Download gesendet wird, anstatt als JSON.

> Dieser eine Aufruf ruft den vollständigen Verlauf jedes übereinstimmenden Kontakts ab. Halten Sie daher `hours` und `limit` bei stark frequentierten Konten in einem angemessenen Rahmen.

### Ein Transkript per E-Mail an den Kontakt senden

`POST /chat-exports/{contactId}/email`

Sendet dem Kontakt sein eigenes Konversationstranskript per E-Mail – der „Sende mir diesen Chat per E-Mail“-Ablauf, gesteuert über Ihr eigenes System.

| Feld | Erforderlich | Beschreibung |
|---|---|---|
| `recipient_email` | Nein | Wohin es gesendet werden soll. Standardmäßig die gespeicherte E-Mail-Adresse des Kontakts. |
| `via` | Nein | `auto` (Standard) wählt den besten Weg, `transactional` sendet es als System-E-Mail, `email_channel` sendet es von Ihrem verbundenen E-Mail-Kanal. |
| `note` | Nein | Eine kurze Zeile von Ihnen, die über dem Transkript angezeigt wird. Bis zu 1000 Zeichen. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'
```

**Antwort** (`200 OK`):

```json
{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}
```

`omittedCount` gibt an, wie viele der ältesten Nachrichten weggelassen wurden, um die E-Mail in einer angemessenen Länge zu halten. Ein `200` bedeutet, dass das Transkript erstellt und für den Versand in die Warteschlange gestellt wurde, nicht, dass es bereits im Posteingang angekommen ist.

---

## KI für einen Kontakt pausieren oder fortsetzen

`PUT /contacts/{contactId}`

Setzen Sie `is_bot_active` auf `false`, um zu verhindern, dass die KI auf einen Kontakt antwortet, und zurück auf `true`, um das Gespräch wieder zu übergeben. Dies ist der Übernahmeschalter, den Sie benötigen, wenn ein Mensch in ein Gespräch eingreift: Ausgehende Nachrichten, die Sie über die API senden, werden weiterhin zugestellt, während der Bot pausiert ist.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});
```

**Python**

```python
import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)
```

**Antwort**

```json
{
  "success": true,
  "contact_id": "contact123"
}
```

**Pausieren als Teil der Antwort**

Wenn ein Mensch durch das Senden einer Antwort übernimmt, können Sie den Bot in derselben Anfrage pausieren, anstatt einen zweiten Aufruf zu tätigen. `POST /contacts/{contactId}/send-message` akzeptiert zwei optionale Flags:

| Feld | Beschreibung |
|---|---|
| `pauseBot` | `true` pausiert die KI für diesen Kontakt, während die Nachricht gesendet wird. |
| `clearIncompleteReply` | `true` verwirft eine halbfertige Bot-Antwort, damit diese danach nicht fortgesetzt wird. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true
  }'
```

Die Antwort enthält `"botPaused": true`, wenn die Pause angewendet wurde.

> Das Markieren eines Kontakts als privat mit [`POST /contacts/bulk-flag`](contacts.md) pausiert ebenfalls den Bot für diesen Kontakt. Siehe [Kontakte](contacts.md) für die vollständige Feldliste.

---

## Eigenen Posteingang erstellen

Alles, was ein Posteingang benötigt, finden Sie auf dieser Seite und unter [Kontakte](contacts.md):

| Was Sie benötigen | Endpunkt |
|---|---|
| Konversationen auflisten | `GET /contacts` |
| Eine Konversation lesen | `GET /contacts/{contactId}/messages` |
| Chat-Sitzungen eines Kontakts auflisten | `GET /chat-sessions/{contactId}` |
| Sehen, was kürzlich eingegangen ist | `GET /chat-sessions/recent` |
| Eine Chat-Sitzung lesen | `GET /contacts/{contactId}/chat-sessions/{sessionId}/messages` |
| Eine manuelle Antwort senden | `POST /contacts/{contactId}/send-message` |
| Eine gerade gesendete Antwort korrigieren | `POST /contacts/{contactId}/messages/{messageId}/edit` |
| Eine Nachricht entfernen | `DELETE /contacts/{contactId}/messages/{messageId}` |
| Mehrere Nachrichten löschen | `POST /contacts/{contactId}/messages/bulk-delete` |
| Mit einem Emoji reagieren | `POST /contacts/{contactId}/messages/{messageId}/react` |
| Eine Nachricht bewerten oder mit einem Stern markieren | `PATCH /contacts/{contactId}/messages/{messageId}` |
| Als gelesen markieren | `POST /contacts/{contactId}/mark-read` |
| Einen Chat an das Team zurückgeben | `POST /contacts/{contactId}/mark-unread` |
| Ein Transkript exportieren | `GET /chat-exports/{contactId}` |
| Die KI pausieren oder fortsetzen | `PUT /contacts/{contactId}` mit `is_bot_active` |

Für Live-Updates abonnieren Sie die Ereignisse `New Message`, `Replies`, `Human Alerted` und `Chat Concluded` mit [Webhooks](webhooks.md), anstatt diese API zeitgesteuert abzufragen.

---

## Fehler der Messages-API

Nachrichten-Endpunkte geben das Standard-Fehler-Envelope zurück:

```json
{
  "success": false,
  "error": "Contact not found"
}
```

| Status | Wann es bei einem Nachrichten-Endpunkt auftritt |
|---|---|
| `400` | Ein erforderliches Feld fehlt oder ein Parameter ist ungültig (falsche `limit`, `hours`, `filter`, `direction`, `status`, ein leeres oder über 500 Elemente umfassendes `message_ids`-Array, ein ungültiges `cursor`, ein leeres oder zu langes Bearbeitungs-`body`, ein `score` außerhalb von `-1`/`0`/`1` oder ein Emoji mit Leerzeichen oder über 16 Zeichen). Wird auch zurückgegeben, wenn eine Nachricht überhaupt nicht bearbeitet werden kann – sie wurde gelöscht, ihr Kanal unterstützt keine Bearbeitung oder das Bearbeitungsfenster des Kanals ist abgelaufen. |
| `404` | Der Kontakt, die Chat-Sitzung oder eine der bereitgestellten Nachrichten-IDs wurde nicht gefunden. |
| `409` | Der Kanal akzeptiert die Änderung derzeit nicht. Es wurde nichts geschrieben: Bei einer Bearbeitung gibt `edit_reason` den Grund an; bei einer Reaktion war der Kanal vorübergehend nicht erreichbar und ein erneuter Versuch könnte funktionieren. |
| `422` | Der Kontakt kann keine ausgehenden Nachrichten empfangen (Nicht-stören-Modus, privat oder ein nicht unterstützter Kanal) oder eine Reaktion kann in dieser Konversation niemals zugestellt werden (`reaction_reason` gibt an, welche). |

Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann — `401`, `403` (Ihr Plan beinhaltet keinen API-Zugriff), `429` (Ratenbegrenzung) und `500` — sind zusammen mit Hinweisen zur Wiederholung unter [Fehler & Paginierung](errors-and-pagination.md) aufgeführt.

---

## Nächste Schritte

- [Webhooks](webhooks.md) — erhalten Sie Zustellungsstatus-Updates per Push, anstatt sie abzufragen.
- [Kontakte](contacts.md) — erstellen und suchen Sie die Kontakte, denen Sie Nachrichten senden.
- [Termine](appointments.md) — buchen und verwalten Sie Termine für Ihre Kontakte.