Benutzerdefinierte Kanäle #

Verbinden Sie jede beliebige Messaging-Plattform oder Kommunikationstool über benutzerdefinierte Kanäle mit der Plattform. So können Sie Nachrichten von Plattformen wie Live-Chat-Widgets auf Websites, E-Mail-Systemen, CRMs oder anderen Diensten in Ihren Posteingang bringen – und mit Ihrem KI-Agenten darauf antworten.

Was sind benutzerdefinierte Kanäle? #

Benutzerdefinierte Kanäle erweitern die Plattform über ihre integrierten Messaging-Plattformen (WhatsApp, SMS, Instagram, Messenger) hinaus. Mit benutzerdefinierten Kanälen können Sie:

• Nachrichten empfangen von jeder externen Plattform in den zentralen Posteingang der Plattform.
• Antworten senden aus der App automatisch zurück an Ihre externe Plattform.
• Einen KI-Agenten verwenden, um auf Nachrichten aus jeder Quelle zu antworten.
• Alle Konversationen verfolgen neben Ihren anderen Kanälen in einem einzigen Posteingang.

Dies ist ideal für Unternehmen, die spezialisierte Kommunikationstools verwenden, eine maßgeschneiderte Plattform besitzen oder alle Kundennachrichten an einem Ort bündeln möchten.

Funktionsweise #

Benutzerdefinierte Kanäle funktionieren durch den Austausch von Nachrichten zwischen Ihrer externen Plattform und der Plattform mithilfe von Webhooks (automatisierte Nachrichten, die über das Internet zwischen Systemen gesendet werden). Hier ist der Ablauf:

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Eingehende Nachrichten: Ihre externe Plattform sendet Nachrichten an eine Webadresse (URL). Stellen Sie es sich so vor, als würde Ihre Plattform eine Nachricht an den Posteingang der Plattform „posten“.
2. Verarbeitung: Die Plattform erstellt oder aktualisiert den Kontakt, speichert die Nachricht und lässt (falls aktiv) einen KI-Agenten eine Antwort generieren.
3. Ausgehende Nachrichten: Wenn die Plattform eine Antwort sendet (egal ob von der KI oder von Ihnen getippt), sendet sie die Nachricht an eine URL auf Ihrer Plattform, von wo aus Ihr System sie an den Endbenutzer zustellen kann.

Einrichten eingehender Nachrichten (Ihre Plattform an die App) #

Um Nachrichten von Ihrer externen Plattform in die App zu senden, muss Ihre Plattform Daten an die folgende URL senden. Ihr Entwickler wird dies als Standard-POST-Anfrage erkennen (eine gängige Methode für ein System, Daten über das Internet an ein anderes zu senden).

Wohin Nachrichten gesendet werden sollen #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

Ersetzen Sie YOUR_API_KEY durch Ihren API-Schlüssel (einen privaten Code, der der Plattform beweist, dass Ihre Plattform Nachrichten senden darf). Sie finden oder generieren ihn unter Einstellungen → Integrationen → API-Schlüssel.

Nachrichtenformat #

Senden Sie die Nachrichtendaten im folgenden Format (JSON):

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

Was die einzelnen Teile bedeuten:

• messageSid - Eine eindeutige ID für diese spezifische Nachricht (wird von Ihrem System erstellt). Wird verwendet, um zu verhindern, dass dieselbe Nachricht zweimal verarbeitet wird.
• fromId - Wer die Nachricht gesendet hat (kann eine Benutzer-ID, E-Mail-Adresse oder Telefonnummer aus Ihrem System sein).
• toId - Ihre Unternehmens-ID (kann eine beliebige Bezeichnung Ihrer Wahl sein).
• body - Der eigentliche Nachrichtentext.
• channel - Eine Bezeichnung Ihrer Wahl, um zu identifizieren, woher die Nachricht stammt (z. B. “website-chat”, “email”).

Vollständige Feldreferenz #

Emoji-Reaktionen #

Wenn Ihre Plattform Emoji-Reaktionen unterstützt (zum Beispiel einen Daumen hoch für eine Nachricht), senden Sie diese als Reaktion anstatt als Textnachricht: Setzen Sie messageType auf "reaction" und fügen Sie nur das Emoji in customData.body ein.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

Der Assistent behandelt dies dann so, wie Sie es erwarten würden:

• Eine Reaktion auf eine Frage des Assistenten (zum Beispiel „Passt Donnerstag?“) wird als Antwort gewertet und der Assistent antwortet darauf.
• Eine Reaktion auf eine Abschlussnachricht (zum Beispiel „Bis bald!“) beendet das Gespräch lautlos. Es wird keine Antwort gesendet.

Wenn Ihre Plattform Reaktionen in Text umwandelt, wie etwa „Reagierte mit: 👍“, sieht der Assistent eine normale Textnachricht und entscheidet selbst, ob er antwortet. Durch das Senden des Reaktionstyps wird dies vermieden.

Was Sie zurückerhalten #

Eine erfolgreiche Anfrage gibt Folgendes zurück:

{
  "success": true,
  "messageId": "1234567890"
}

Wenn etwas schiefgeht, erhalten Sie eine Fehlermeldung, die das Problem erklärt:

{
  "error": "Message body cannot be empty"
}

Statuscodes #

Wenn Sie customData.status festlegen, ist der einzige akzeptierte Wert "received" — lassen Sie ihn ganz weg, um den Standardwert zu verwenden, anstatt etwas anderes zu senden, da Sie sonst einen 400 erhalten.

Senden von Medienanhängen (Bilder, Videos, Dateien) #

Sie können Dateianhänge (Bilder, Videos, Audio, Dokumente) in Ihre Nachrichten einfügen. Es gibt zwei Möglichkeiten, dies zu tun:

Option 1: Link zu einer Datei #

Wenn die Datei bereits online gehostet ist, geben Sie die URL (Webadresse) an, unter der die Plattform sie herunterladen kann:

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Option 2: Datei direkt einbetten (Base64) #

Wenn die Datei nicht online gehostet wird, können Sie sie direkt als kodierten Text (Base64-Format) in die Nachricht einbetten. Dies ist bei technischen Integrationen üblich, bei denen Ihr System Dateien dynamisch generiert. Die Plattform dekodiert die Datei automatisch und speichert sie:

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Einrichten ausgehender Nachrichten (von der Plattform an Ihre Plattform) #

Wenn die Plattform eine Antwort über einen benutzerdefinierten Kanal sendet (egal ob von der KI oder von Ihnen getippt), sendet sie diese Antwort automatisch an eine URL auf Ihrer Plattform, damit Ihr System sie an den Endbenutzer zustellen kann.

Legen Sie zuerst die Webhook-URL fest. Sie müssen die Webhook-URL des benutzerdefinierten Kanals speichern, bevor Antworten zugestellt werden können. Wenn keine URL gespeichert ist, werden Antworten zwar generiert und gespeichert, aber nie versendet – und sie zeigen keinen „Fehlgeschlagen“-Status an, sodass nichts in Ihrem Posteingang auf das Problem hinweist. Konfigurieren Sie die Webhook-URL immer, bevor Sie live gehen.

Der App mitteilen, wohin Antworten gesendet werden sollen #

1. Klicken Sie in der linken Seitenleiste unten auf Einstellungen.
2. Klicken Sie in der linken Einstellungsleiste unter Kanäle auf Kanäle.
3. Suchen Sie die Karte Benutzerdefinierter Kanal ganz unten auf der Seite (nach Android SMS Gateway, iMessage, dem Website-Chat-Widget, Twilio-Konto und Einhaltung gesetzlicher Vorschriften).
4. Geben Sie die Webhook-URL ein — die URL auf Ihrer Plattform, an die die KI ausgehende Nachrichten senden soll (Ihr Entwickler richtet dies ein, um Antworten zu empfangen und zu verarbeiten). Es muss eine öffentliche HTTPS-URL sein — http://-Adressen und nicht öffentliche Hosts werden abgelehnt.
5. Klicken Sie auf Speichern.

Was die Plattform an Ihre Plattform sendet #

Wenn die Plattform eine Antwort sendet, empfängt Ihre Plattform die folgenden Daten:

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}

Was die einzelnen Felder bedeuten #

Ihre Plattform empfängt diese Daten und verwendet sie, um die Antwort über Ihr eigenes System an den Endbenutzer zuzustellen.

Wie die Plattform die Zustellung nachverfolgt #

Nachdem die Antwort an Ihre Plattform gesendet wurde, aktualisiert die Plattform den Nachrichtenstatus:

• Gesendet - Ihre Plattform hat die Nachricht erfolgreich empfangen.
• Fehlgeschlagen - Ihre Plattform hat einen Fehler zurückgegeben oder war nicht erreichbar. Die Plattform speichert die Fehlerdetails zusammen mit der Nachricht, damit Sie diese zur Fehlerbehebung nutzen können.

Senden von Nachrichten von Ihrem System an die App #

Zusätzlich zum Empfang von Nachrichten können Sie über einen benutzerdefinierten Kanal auch ausgehende Nachrichten direkt von Ihrem eigenen System aus senden. Dies ist nützlich, wenn Sie eine Konversation beginnen oder eine proaktive Nachricht senden möchten.

Plananforderung. Das Senden und Synchronisieren von Nachrichten über die API erfordert einen Plan, der API-Zugriff und mindestens einen Messaging-Kanal beinhaltet. Wenn Sie einen 403 “permission denied / feature not enabled”-Fehler erhalten, ist dies in Ihrem aktuellen Plan nicht enthalten – führen Sie ein Upgrade Ihres Plans durch oder kontaktieren Sie den Support.

Wohin senden #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Nachrichtenformat #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Erforderliche Felder #

Die optionalen Felder (campaignId, firstName, lastName, email) funktionieren genauso wie bei eingehenden Nachrichten – sie helfen der Plattform, den Kontaktdatensatz zu erstellen oder zu aktualisieren.

Was Sie zurückerhalten #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Aufzeichnen von Nachrichten, die von einem anderen System gesendet wurden #

Manchmal haben Sie bereits eine Nachricht von einem anderen Tool an einen Kontakt gesendet (zum Beispiel über einen Workflow in einer anderen Plattform) und möchten lediglich, dass die Plattform davon erfährt, damit die KI den vollständigen Kontext hat. Dies unterscheidet sich vom Senden: Die Plattform zeichnet die Nachricht auf, stellt sie aber nicht erneut an den Kontakt zu.

Wohin senden #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

Geben Sie customData.fromId (die ID des Kontakts auf Ihrer Plattform) und customData.body (den bereits gesendeten Nachrichtentext) an.

Funktionsweise #

• Die Nachricht wird aufgezeichnet, nicht erneut gesendet. Die Plattform speichert sie nur zur Kontextbildung in der Konversation.
• Die KI ist bei diesem Kontakt standardmäßig pausiert. Dies verhindert, dass der Bot auf eine Nachricht antwortet, die bereits von einem Menschen bearbeitet wurde. Um den Bot aktiv zu halten, übergeben Sie customData.pauseAi: false.
• Neue Kontakte können automatisch erstellt werden. Fügen Sie customData.customChannel hinzu, und der Kontakt wird erstellt, falls er noch nicht existiert.
• Duplikate werden ignoriert. Wenn Sie dieselbe messageSid wiederverwenden, erkennt die Plattform, dass die Nachricht bereits aufgezeichnet wurde, und nimmt keine Änderungen vor.

Plananforderung. Wie beim Senden erfordert auch das Aufzeichnen von Nachrichten über die API einen Plan, der API-Zugriff und mindestens einen Messaging-Kanal beinhaltet. Ein 403 “permission denied / feature not enabled”-Fehler bedeutet, dass Ihr aktueller Plan dies nicht enthält.

Praxisbeispiele #

Website-Live-Chat #

Verbinden Sie ein Live-Chat-Widget auf Ihrer Website mit der Plattform, damit Ihr KI-Agent Fragen von Besuchern beantworten kann:

1. Ein Besucher tippt eine Nachricht in das Chat-Widget Ihrer Website ein.
2. Ihr Chat-Widget sendet die Nachricht an die Plattform.
3. Der KI-Agent generiert eine Antwort.
4. Die Antwort wird an Ihr Chat-Widget zurückgesendet, das sie dem Besucher anzeigt.

Warum das nützlich ist: Ihre Website-Besucher erhalten sofort KI-gestützte Antworten auf ihre Fragen, ohne dass Sie online sein müssen.

E-Mail #

Leiten Sie E-Mail-Konversationen über die Plattform weiter, damit Ihr KI-Agent auf E-Mails antworten kann:

1. Richten Sie ein System ein, das eingehende E-Mails an die Plattform weiterleitet (unter Verwendung der Absenderadresse als fromId, des E-Mail-Betreffs und -Textkörpers als body sowie "email" als channel).
2. Der KI-Agent liest die E-Mail und generiert eine Antwort.
3. Die Antwort wird an Ihr E-Mail-System zurückgesendet, das sie als normale E-Mail-Antwort verschickt.

Warum das nützlich ist: Häufige E-Mail-Fragen (Preise, Öffnungszeiten, Verfügbarkeit) werden sofort von Ihrem KI-Agenten beantwortet.

Wenn Ihr E-Mail-System IMAP/SMTP oder OAuth unterstützt, ist der integrierte E-Mail-Kanal möglicherweise einfacher als eine benutzerdefinierte Integration.

CRM-Integration #

Verbinden Sie Ihr bestehendes CRM-System (Customer Relationship Management) mit der Plattform:

1. Wenn ein Lead eine Nachricht über Ihr CRM sendet, leiten Sie diese an die Plattform weiter.
2. Der KI-Agent antwortet und verfolgt die Konversation.
3. Die KI-Antwort wird zur Zustellung an Ihr CRM zurückgesendet.
4. Der vollständige Konversationsverlauf ist sowohl auf der Plattform als auch in Ihrem CRM verfügbar.

Warum das nützlich ist: Ihr Vertriebsteam erhält KI-unterstützte Antworten an Leads, ohne das CRM verlassen zu müssen.

Support-Ticket-System #

Nutzen Sie die Plattform als KI-gestützte erste Anlaufstelle für den Kundensupport:

1. Ihr Ticketsystem leitet neue Support-Tickets an die Plattform weiter.
2. Der KI-Agent sendet eine erste Antwort (z. B. Bestätigung des Tickets und Rückfragen zur Klärung).
3. Die Antwort wird an das Ticket in Ihrem Support-System angehängt.
4. Ihr Support-Team kann überprüfen, was die KI gesagt hat, und bei Bedarf übernehmen.

Warum das nützlich ist: Kunden erhalten eine sofortige Bestätigung und erste Hilfe, auch außerhalb der Geschäftszeiten.

Fehlerbehebung #

Nachrichten werden nicht von der Plattform empfangen #

• Überprüfen Sie, ob Ihr API-Schlüssel korrekt und aktiv ist (siehe Einstellungen → Integrationen → API-Schlüssel).
• Stellen Sie sicher, dass Sie eine POST-Anfrage senden (keine GET-Anfrage). Ihr Entwickler kennt den Unterschied.
• Prüfen Sie, ob das Feld customData.body nicht leer ist oder nur aus Leerzeichen besteht.
• Stellen Sie sicher, dass das Feld customData.fromId enthalten ist.
• Lesen Sie die Antwortnachricht für spezifische Fehlerdetails.

Antworten erreichen Ihre Plattform nicht #

• Stellen Sie sicher, dass Sie die URL Ihrer Plattform in der Karte Benutzerdefinierter Kanal auf der Seite „Kanäle“ eingegeben haben. Wenn keine URL gespeichert ist, werden Antworten zwar generiert und gespeichert, aber nie versendet — und sie werden nicht als „Fehlgeschlagen“ markiert. Überprüfen Sie dies also zuerst.
• Stellen Sie sicher, dass die URL öffentlich zugänglich ist (nicht hinter einem Login oder einer Firewall) und eine Erfolgsmeldung zurückgibt.
• Nur Antworten (ausgehende Nachrichten) werden an Ihre URL gesendet — eingehende Nachrichten lösen dies nicht aus.
• Überprüfen Sie die Fehlerdetails zur Nachricht in Ihrem Posteingang.

Kontakt wird nicht erstellt #

• Stellen Sie sicher, dass der Wert fromId für denselben Benutzer über alle seine Nachrichten hinweg konsistent ist. Die Plattform verwendet diesen Wert zur Identifizierung von Kontakten — wenn er sich zwischen Nachrichten ändert, erstellt die Plattform jedes Mal einen neuen Kontakt.
• Fügen Sie firstName, lastName und email in die erste Nachricht eines neuen Kontakts ein, um einen vollständigen Kontaktdatensatz zu erstellen.

Medienanhänge funktionieren nicht #

• Stellen Sie bei Dateilinks (URLs) sicher, dass die Datei öffentlich zugänglich ist (kein Login erforderlich).
• Fügen Sie immer mediaContentType hinzu, wenn Sie mediaUrl einfügen.
• Überprüfen Sie bei eingebetteten Dateien (base64), ob das Format data:MIME_TYPE;base64,ENCODED_DATA ist.
• Stellen Sie sicher, dass der von Ihnen angegebene Dateityp mit dem tatsächlichen Dateiinhalt übereinstimmt.

Best Practices #

• Verwenden Sie konsistente fromId-Werte. Jeder Benutzer auf Ihrer Plattform sollte immer dieselbe fromId haben. Dies stellt sicher, dass die Plattform alle seine Nachrichten in einer einzigen Konversation gruppiert, anstatt doppelte Kontakte zu erstellen.
• Wählen Sie einen eindeutigen channel-Namen. Wählen Sie etwas Beschreibendes wie "website-chat", "email" oder "zendesk", damit Sie beim Betrachten Ihres Posteingangs leicht erkennen können, woher die Nachrichten stammen.
• Fügen Sie Kontaktdetails (firstName, lastName, email) in die erste Nachricht eines neuen Kontakts ein. Dies erstellt sofort einen vollständigen, nützlichen Kontaktdatensatz.
• Bauen Sie eine Wiederholungslogik ein. Lassen Sie Ihre Plattform das Senden von Nachrichten wiederholen, falls die Plattform beim ersten Versuch nicht antwortet (Netzwerkprobleme kommen vor).
• Verwenden Sie eindeutige messageSid-Werte für jede Nachricht. Dies verhindert, dass dieselbe Nachricht zweimal verarbeitet wird, falls Ihr System sie mehr als einmal sendet.
• Verwenden Sie campaignId, um Nachrichten an verschiedene KI-Agenten weiterzuleiten, wenn Sie mehrere Anwendungsfälle haben (z. B. Verkaufsanfragen vs. Support-Fragen).
• Testen Sie vor dem Livegang. Senden Sie Testnachrichten in beide Richtungen und überprüfen Sie, ob Kontakte, Konversationen und KI-Antworten korrekt funktionieren, bevor Sie für echte Benutzer starten.