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 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 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.

Beide finden ebenfalls nur Kontakte, die bereits existieren. Keiner der Aufrufe erstellt einen: Wenn eine ID oder Identität zu nichts passt, wird 404 zurückgegeben; es wird kein neuer Kontakt angelegt. Wenn Sie also jemandem zum ersten Mal schreiben, erstellen Sie entweder zuerst den Kontakt mit POST /contacts oder verwenden Sie in WhatsApp Web unten Direkt an eine WhatsApp Web-Nummer senden, wodurch der Kontakt im selben Aufruf erstellt wird.

Senden per Kontakt-ID #

POST /contacts/{contactId}/send-message

Auf LinkedIn wird eine Nachricht, die Sie auf diese Weise oder über den Posteingang senden, auch dann zugestellt, wenn eine Person den Thread auf der LinkedIn-Seite bearbeitet. Die eigenen Antworten der KI und ihre Nachfassaktionen werden in einem solchen Thread zurückgehalten. Eine zurückgehaltene Antwort wird aus dem Chat entfernt, anstatt als fehlgeschlagen angezeigt zu werden, da nichts gesendet wurde und kein Guthaben verbraucht wird. Die letzte Antwort der KI, bevor sie einen Thread an eine Person übergibt, wird weiterhin zugestellt.

cURL

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

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

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):

{
  "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.

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=)

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

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

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):

{
  "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.

Senden über WhatsApp Web: Variationen und Schutz vor Nachrichtenfluten #

Für body gelten zwei Dinge, wenn der Kontakt WhatsApp Web verwendet.

Spintax-Klammern werden pro Versand aufgelöst. Ein body von {Hi|Hello|Hey} there, quick question wird als eine der drei Begrüßungen versendet, die für diesen Versand ausgewählt wurde – die Klammern erreichen den Kontakt niemals. Verwenden Sie dies, um jedem Kontakt eine unterschiedliche Eröffnungsnachricht mit demselben Integrationscode zu senden. Text ohne Klammern wird exakt so gesendet, wie er geschrieben wurde.

Häufungen identischer Eröffnungsnachrichten werden abgelehnt. Wenn innerhalb einer Stunde zehn nahezu identische Eröffnungsnachrichten von einer WhatsApp Web-Nummer an Kontakte gesendet werden, die Ihnen noch nie geschrieben haben, werden weitere Nachrichten nicht zugestellt: Der Versand wird wie gewohnt akzeptiert (Sie erhalten weiterhin ein messageId), aber die Nachricht verbleibt dann mit status: "failed" und error_code: "opener_burst", versehen mit einem für den Kunden lesbaren Grund. Ein erneuter Versuch mit demselben Text hilft nicht – variieren Sie den Text, warten Sie eine Stunde und senden Sie erneut. Antworten innerhalb bestehender Konversationen sind davon nie betroffen. Die Begründung finden Sie unter Identische Eröffnungsnachrichten führen zu Einschränkungen der Nummern.

Direkt an eine WhatsApp Web-Nummer senden #

POST /whatsapp-web/send

Senden Sie eine Nachricht an eine Telefonnummer in WhatsApp Web, ohne vorher nach einem Kontakt zu suchen. Wenn die Nummer noch kein Kontakt ist, wird der Kontakt im selben Aufruf erstellt, wobei die KI dafür ausgeschaltet ist, sodass die Nachricht wie eine von Ihnen manuell gesendete Nachricht aussieht und kein Assistent das Gespräch danach übernimmt. Ein bestehender Kontakt wird unverändert wiederverwendet.

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

Ein erfolgreicher Aufruf antwortet mit 202:

{ "success": true, "queued": true, "contactId": "abc123" }

202 bedeutet akzeptiert, aber noch nicht zugestellt. Außerhalb der aktiven Stunden wird der Versand zurückgehalten und im nächsten erlaubten Zeitfenster ausgeführt, es sei denn, Sie haben ignoreActiveHours übergeben. Lesen Sie den Status der Nachricht mit Nachrichten eines Kontakts auflisten unter Verwendung der contactId, die Sie hier erhalten haben, wieder aus.

Wenn es nicht durchgeht:

Ein zweiter Aufruf für denselben Kontakt, während ein zurückgehaltener Versand noch wartet, antwortet mit 409, sodass sich niemals eine Warteschlange hinter einer Person ansammelt.

Eine Notiz in einer Konversation protokollieren #

POST /contacts/notes

Fügt eine Zeile zur Konversation eines Kontakts hinzu, ohne sie zu versenden. Verwenden Sie dies für Kontext, den Ihr Team und die KI kennen sollten, der Kontakt aber niemals erhalten darf: eine Zusammenfassung eines Telefonats, das Ihr Voice-Agent gerade geführt hat, eine Anmerkung aus Ihrem CRM oder eine Notiz von einem Kollegen. Dies funktioniert auf jedem Kanal (WhatsApp, SMS, Instagram, Messenger, Telegram, Chat-Widget, benutzerdefinierte Kanäle usw.).

Was mit einer Notiz geschieht:

• Sie erscheint im Chat im Posteingang als gelbe Notiz-Karte, zusammen mit dem Autor, falls Sie einen angegeben haben.
• Die KI liest sie als Teil des Konversationsverlaufs, markiert als interne Notiz, sodass ihre nächste Antwort diese berücksichtigt.
• Sie wird niemals an den Kontakt gesendet, verbraucht keine Nachrichtenguthaben und löst nichts aus: keine KI-Antwort, keine Automatisierung, kein Webhook, keine Benachrichtigung, kein ungelesen-Badge. Sie pausiert die KI nicht und zählt nicht als Antwort Ihres Teams.

Finden Sie den Kontakt auf die gleiche Weise wie unter Nach Kontaktidentität senden: entweder über dessen ID oder über ein channel plus den passenden Identifikator. Eine Notiz kann nur an einen bereits existierenden Kontakt gesendet werden; wenn nichts gefunden wird, ist das ein 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

Antwort (201 oder 200 mit duplicate: true, wenn die external_id bereits protokolliert wurde)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

Eine Notiz erscheint unter Nachrichten eines Kontakts auflisten mit type: "note".

Einen Antwortentwurf mit der KI erstellen #

POST /contacts/{contactId}/draft-reply

Fordert den KI-Agenten, der eine Unterhaltung verwaltet, dazu auf, die nächste Antwort zu schreiben, und gibt Ihnen den Text zurück. Es wird nichts gesendet. Es handelt sich um denselben Entwurf, den die Schaltfläche Antwort generieren im Posteingang erstellt: Der Agent nutzt seine Konfiguration, seine Wissensdatenbank und den bisherigen Verlauf der Unterhaltung und antwortet in der Sprache des Kontakts. Verwenden Sie dies, um einen Menschen (oder Ihre eigene App) zwischen die KI und den Kontakt zu schalten: Rufen Sie den Entwurf ab, zeigen Sie ihn zur Genehmigung an und senden Sie ihn dann mit Nach Kontakt-ID senden – entweder unverändert oder angepasst.

• Der Entwurf wird von dem Agenten geschrieben, der dem Kontakt zugewiesen ist. Ein Kontakt, der noch keinen Agenten hat, erhält den Agenten, der auf seine nächste Nachricht antworten würde.
• Während der Erstellung des Entwurfs führt der Agent keine Tools oder Funktionen aus, sodass keine Buchungen, Tags, Übergaben oder andere Aktionen stattfinden.
• Es wird nichts in der Unterhaltung gespeichert und der Kontakt sieht nichts.
• Ein Entwurf kostet die gleichen Credits wie eine KI-Antwort dieses Agenten in dieser Unterhaltung; wenn Ihr eigener KI-Schlüssel verbunden ist, entstehen keine Kosten.
• Die Unterhaltung muss mindestens eine Nachricht enthalten.

Alle Body-Felder sind optional; ein leerer Body (oder kein Body) erstellt einen Entwurf für die nächste Antwort.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

Antwort (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

Ein 400 bedeutet, dass die Unterhaltung noch keine Nachrichten enthält, Ihre Credits aufgebraucht sind oder der Kontakt keinen Agenten oder keine Kampagne für den Entwurf hat (error gibt an, woran es liegt). Ein 404 bedeutet, dass der Kontakt nicht existiert oder der Schlüssel eines Teammitglieds auf Kontakte beschränkt ist, die es nicht sehen kann. Der Schlüssel oder das Teammitglied benötigt die Berechtigung zum Bearbeiten von Nachrichten.

Verwenden Sie einen KI-Client über MCP? Die gleiche Aktion ist als generate_reply_draft-Tool verfügbar.

Nachrichten eines Kontakts auflisten #

GET /contacts/{contactId}/messages

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

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

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

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

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):

{
  "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 #

Anhang einer Nachricht herunterladen #

POST /chat-exports/media/download-url

Gibt Ihnen einen neuen Download-Link für die an eine Nachricht angehängte Datei: ein Bild, eine Sprachnachricht, ein Video oder ein Dokument. Der Link ist 1 Stunde lang gültig. Verwenden Sie ihn, wenn Sie Anhänge an einem anderen Ort speichern möchten (zum Beispiel beim Archivieren von Lebensläufen oder Sprachnachrichten eines Kontakts) oder wenn der media_url einer Nachricht oder ein New Message Webhook sich nicht mehr öffnen lässt.

Um Nachrichten mit Anhängen zu finden, listen Sie die Nachrichten eines Kontakts mit filter=media auf. Die id jeder Nachricht und die ID des Kontakts bilden die messagePath.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

Antwort (200 OK):

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

Verwenden Sie einen KI-Client über MCP? Die gleiche Aktion ist als get_chat_media_download_url-Tool verfügbar.

Chat-Sitzungen auflisten #

Eine Chat-Sitzung ist ein Konversationsfenster mit einem Kontakt. Sie öffnet sich bei der ersten eingehenden Nachricht, wenn keine Sitzung geöffnet ist, und schließt sich automatisch 48 Stunden nach der letzten eingehenden Nachricht des Kontakts (jede neue eingehende Nachricht verschiebt die Schließung um weitere 48 Stunden). Wenn die KI einen Chat beendet, wird die Sitzung nicht geschlossen; es wird lediglich der Webhook „Chat beendet“ ausgelöst. Sitzungen dienen dazu, 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.

cURL

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

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

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):

{
  "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

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

Antwort (200 OK):

{
  "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

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

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

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):

{
  "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 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

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.

Im Gegensatz zum Löschen schlägt dies lautstark fehl, wenn der Kanal dies verweigert: Sie erhalten einen 409 und Ihre Kopie bleibt genau so, wie der Kontakt sie hat, da das Anzeigen einer Bearbeitung, die er nie erhalten hat, dazu führen würde, dass beide Seiten nicht mehr synchron sind. Das Feld edit_reason gibt Ihnen den Grund an – das Bearbeitungsfenster des Kanals ist abgelaufen, der Kanal ist getrennt, die Nachricht enthält einen Anhang, den der Kanal nicht bearbeiten kann (media_not_editable: bei WhatsApp Web können nur Textnachrichten bearbeitet werden, nicht der Text unter einem Foto, Video oder einer Datei) oder etwas anderes ist schiefgelaufen.

cURL

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

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

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):

{
  "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:

{
  "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:

cURL

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

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

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):

{
  "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.

cURL

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

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

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):

{
  "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.

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

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

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

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):

{
  "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.

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

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

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

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):

{
  "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.

cURL

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

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

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):

{
  "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

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

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

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):

{
  "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

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

Antwort (200 OK):

{
  "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}

cURL

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

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):

{
  "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:

{
  "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.

cURL

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

Antwort (200 OK):

{
  "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.

cURL

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):

{
  "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

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

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

import requests

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

Antwort

{
  "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 diese optionalen Flags:

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,
    "human_reply": true
  }'

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

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

Eigenen Posteingang erstellen #

Alles, was ein Posteingang benötigt, finden Sie auf dieser Seite und unter Kontakte:

Für Live-Updates abonnieren Sie die Ereignisse New Message, Replies, Human Alerted und Chat Concluded mit Webhooks, anstatt diese API zeitgesteuert abzufragen.

Fehler der Messages-API #

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

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

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 aufgeführt.

Nächste Schritte #

• Webhooks — erhalten Sie Zustellungsstatus-Updates per Push, anstatt sie abzufragen.
• Kontakte — erstellen und suchen Sie die Kontakte, denen Sie Nachrichten senden.
• Termine — buchen und verwalten Sie Termine für Ihre Kontakte.