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.

Senden per Kontakt-ID #

POST /contacts/{contactId}/send-message

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.

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 #

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.

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

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 zwei optionale 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
  }'

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.