Telnyx Messaging

So funktionieren eingehende Nachrichten

Telnyx sendet signierte JSON-Ereignisse an den Webhook der Verbindung. Connic prüft jede eingehende Nachricht, bereitet die Eingabe auf und legt einen Run pro verknüpftem Agenten an. Antworten versendet eine separate Outbound-Verbindung.

Beide Richtungen können denselben gespeicherten Kontozugang wie Telnyx Voice verwenden. Er enthält den API-Schlüssel und den öffentlichen Schlüssel. Kanal und Absender werden für jede Messaging-Verbindung einzeln festgelegt.

Inbound einrichten

1. 1

   Telnyx-Absender vorbereiten

   Verwende eine Telnyx-Rufnummer mit Messaging-Unterstützung oder eine aktivierte, registrierte WhatsApp-Nummer beziehungsweise einen RCS-Agenten. Verwende für SMS und WhatsApp ein Messaging-Profil, das nur dieser Nummer zugeordnet ist. Verschiebe weitere Nummern und Kurzwahlnummern in ein anderes Profil. Entferne am ausgewählten Profil oder RCS-Agenten vorhandene Ausweich-Webhooks und die Zuordnung zu einem Telnyx-KI-Assistenten.

2. 2

   Eingehende Verbindung anlegen

   Füge Telnyx Messaging aus dem Marktplatz hinzu und wähle Inbound. Wähle einen gespeicherten Telnyx-Kontozugang oder lege einen mit API-Schlüssel und öffentlichem Kontoschlüssel an. Wähle den Kanal und anschließend den Absender aus der Auswahlliste des Kontos. Speichere die Verbindung.

3. 3

   Nachrichtenzustellung einrichten

   Connic trägt den Webhook automatisch am zugewiesenen Messaging-Profil der Nummer oder am ausgewählten RCS-Agenten ein. Gib für eine externe WhatsApp-Nummer ohne auffindbare Telnyx-Rufnummernzuordnung ihre bestehende Profil-ID an und schließe die unten beschriebene manuelle Einrichtung ab.

4. 4

   Agenten verknüpfen und testen

   Verknüpfe einen bereitgestellten Agenten und halte die Verbindung aktiviert. Sende eine Nachricht an den ausgewählten Absender und prüfe die Run-Eingabe. Ergänze für automatische Antworten eine Outbound-Verbindung mit demselben Kontozugang, Kanal, Absender und Messaging-Profil.

Externe WhatsApp-Nummern

Eine bei Telnyx registrierte WhatsApp-Nummer benötigt eine manuelle Einrichtung, wenn Connic ihre Zuordnung zum Messaging-Profil nicht ermitteln kann. Trage die bestehende Profil-ID in whatsapp_profile_id ein. Connic prüft, ob das Profil zum Konto gehört. Die Nachrichtenzustellung der externen Nummer an dieses Profil lässt sich damit noch nicht bestätigen.

Kopiere nach dem Speichern Incoming-message webhook aus den Verbindungsdetails. Trage die URL in Telnyx als primären Webhook am Messaging-Profil der Nummer ein und wähle Webhook-API-Version 2. Stelle sicher, dass eingehende Nachrichten dieser Nummer an das Profil geleitet werden. Der Webhook für Statusänderungen des WhatsApp Business Accounts ist eine separate Einstellung und ersetzt diese Nachrichtenweiterleitung nicht.

Inbound-Konfiguration

• Telnyx-Kontozugang: Gespeicherte Zugangsdaten, die auch andere Telnyx-Verbindungen verwenden können.
• Kanal und Absender: SMS/MMS, WhatsApp oder RCS und ein Absender aus dem verbundenen Konto. Für jeden Kanal und Absender wird eine eigene Verbindung angelegt.
• WhatsApp-Messaging-Profil: Die bestehende Profil-ID ist erforderlich, wenn Connic die Zuordnung der WhatsApp-Nummer nicht ermitteln kann. Sie wird auch für ausgehende Nachrichten dieser Nummer benötigt.
• Incoming-message webhook: Wird beim Speichern erzeugt. Bei automatischer Einrichtung trägt Connic ihn ein; bei manueller WhatsApp-Einrichtung wird er zum Übertragen nach Telnyx angezeigt.

Gemeinsame Rufnummern

SMS und WhatsApp können dieselbe Nummer mit getrennten Verbindungen und Agenten verwenden. Verwende dafür denselben gespeicherten Telnyx-Kontozugang und dasselbe Rufnummernprofil. Beide Kanäle teilen eine Webhook-Adresse; Connic ordnet Nachrichten anhand von Kanal und Empfänger zu. Das Profil darf keine fremden Nummern oder Kurzwahlnummern enthalten.

Beim Entfernen einer Verbindung bleibt der andere Kanal erreichbar. Beim Absenderwechsel oder Entfernen der letzten eingehenden Verbindung löscht Connic den alten Webhook nur, wenn er noch der Connic-URL entspricht. Das gilt auch für einen manuell eingetragenen WhatsApp-Webhook. Eine später in Telnyx eingetragene andere URL bleibt erhalten. Die Messaging-Einrichtung ändert die Voice-Anwendung der Nummer nicht.

Agent-Input und Sessions

Das Beispiel zeigt die vereinheitlichten Nachrichtenfelder. Zusätzlich enthält der Input unter raw die ursprünglichen Telnyx-Nachrichtendaten. Rufnummern stehen im E.164-Format ohne Kanalpräfix; bei RCS ist der Empfänger die Agent-ID.

{
  "event_id": "7a3a86b3-0e77-48f6-914a-63ad28b7d64e",
  "message_id": "4031938e-60e4-4235-a8dd-0b1c55a23e7a",
  "channel": "whatsapp",
  "from": "+14155550124",
  "to": "+14155550123",
  "text": "Wurde Bestellung 12345 verschickt?",
  "conversation_id": "telnyx_messaging:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091"
}

Setze für einen fortlaufenden Gesprächsverlauf session.key auf input.conversation_id und stelle den Agenten erneut bereit. Sessions werden nicht automatisch aktiviert. Die Gesprächskennung trennt Verbindungen, Kanäle, Absender und Kunden. Im Beispiel bleibt der Verlauf 86.400 Sekunden erhalten.

name: messaging-assistant
model: connic/gpt-5.6-terra
system: |
  Beantworte die eingehende Nachricht kurz.
  Frage nach fehlenden Angaben, statt Annahmen zu treffen.
  Gib die Antwort als einfachen Text zurück.
session:
  key: input.conversation_id
  ttl: 86400

Eingehende Medien

Connic lädt unterstützte Anhänge herunter und übergibt sie unter files. Jede Datei enthält name, mime_type, Base64-kodierte data und die Byteanzahl size. Pro Nachricht sind bis zu 10 Anhänge mit insgesamt höchstens 10 MiB möglich.

Bei nicht verfügbaren oder zu großen Anhängen schlägt der Webhook fehl, bevor ein Agent startet. Reine Mediennachrichten können ein leeres text-Feld enthalten. Berücksichtige files im Agenten und wähle ein Modell, das die jeweiligen Medien verarbeiten kann.

Fehler bei eingehenden Nachrichten

• Speichern schlägt fehl: Prüfe den gemeldeten Telnyx-Fehler. Aktiviere Absender und Profil und entferne fremde Profilzuordnungen sowie konkurrierende Ausweich-Webhooks und KI-Assistenten.
• Kein Agenten-Run: Prüfe die aktivierte Verbindung, das verknüpfte Deployment und die exakte Webhook-URL. Prüfe bei manueller WhatsApp-Einrichtung außerdem die Profilzuordnung der Nummer und Webhook-API-Version 2 in Telnyx.
• Signatur- oder Absenderfehler: Verwende den öffentlichen Schlüssel des verbundenen Telnyx-Kontos. Kanal, Absender und Profil müssen zur eingehenden Nachricht passen.
• Fehler beim Anhang: Prüfe die Webhook-Zustelldetails in Telnyx. Die Medien müssen verfügbar sein und zusammen unter dem Downloadlimit liegen.

Outbound einrichten

1. 1

   Kontozugang und Absender auswählen

   Lege Telnyx Messaging im Outbound-Modus an. Wähle den gespeicherten Kontozugang, Kanal und Absender. Für Antworten müssen Kontozugang, Kanal, Absender und Profil mit der eingehenden Verbindung übereinstimmen. Externe WhatsApp-Nummern benötigen dieselbe whatsapp_profile_id.

2. 2

   Optionale Vorgaben festlegen

   Trage für Benachrichtigungen einen Standardempfänger ein. Für Antworten an den jeweiligen Kunden bleibt das Feld leer. Hinterlege bei Bedarf eine WhatsApp-Vorlage als Standard und speichere die Verbindung. Die ausgehende Einrichtung trägt keinen Webhook für eingehende Nachrichten ein.

3. 3

   Versandart des Agenten festlegen

   Verknüpfe die Verbindung als automatische Outbound-Verbindung, Agent-Tool oder Middleware-Outbound-Verbindung. Wähle für automatische Antworten unter Only selected inputs in den Einstellungen der Agentenverknüpfung die eingehende Verbindung aus. Benachrichtigungen benötigen einen expliziten oder gespeicherten Empfänger.

4. 4

   Erste Nachricht prüfen

   Starte den verknüpften Agenten oder rufe die Verbindung auf. Prüfe den ausgehenden Verbindungs-Run und suche anschließend in Telnyx nach der zurückgegebenen Nachrichten-ID, um die Zustellung zu prüfen.

Payload für ausgehende Nachrichten

Automatische Outbound-Verbindungen akzeptieren einfachen Text oder ein JSON-Objekt. Agent-Tool- und Middleware-Aufrufe verwenden ein Objekt mit text und optional to, media_urls, media_type oder whatsapp_template. Middleware ruft die konfigurierte Verbindung über send_connector auf.

{
  "to": "+14155550124",
  "text": "Das Versandetikett",
  "media_urls": ["https://example.com/shipping-label.png"],
  "media_type": "image"
}

Das Beispiel versendet ein WhatsApp-Bild mit Textbeschreibung. Beim automatischen Versand kann der Text auch in body, message, response oder output stehen. Explizite Aufrufe verwenden text. Die Nachricht muss Text, Medien oder eine Vorlage enthalten; bei reinen Mediennachrichten kann Text entfallen.

Limits für Text und Medien

Übergib in media_urls öffentliche HTTP- oder HTTPS-URLs ohne eingebettete Zugangsdaten. Telnyx ruft die Dateien ab. Ausgehende Medien verwenden URLs, nicht das Base64-Format unter files aus eingehenden Anhängen.

• SMS/MMS: Bis zu 10 Medien-URLs. Mit Medien wird die Nachricht als MMS versendet. Die Telnyx-API begrenzt deren gesamte Mediengröße auf 1 MB.
• WhatsApp: Text darf bis zu 4096 UTF-8-Bytes enthalten. Eine Medien-URL benötigt media_type: image, video, document, audio oder sticker. Bilder, Videos und Dokumente akzeptieren Textbeschreibungen mit bis zu 1024 UTF-8-Bytes. Audio und Sticker werden getrennt vom Text versendet.
• RCS: Text darf bis zu 3072 Zeichen enthalten. Alternativ ist eine Medien-URL möglich. Text und Medien müssen getrennt versendet werden.

WhatsApp-Vorlagen

Außerhalb des Antwortfensters für den WhatsApp-Kundenservice ist eine genehmigte Vorlage erforderlich. Hinterlege whatsapp_template als Standard an der Verbindung oder für eine einzelne Nachricht im Payload. Gib dazu template_id oder name und language.code an. Optionale components enthalten Parameter im Telnyx-WhatsApp-Format.

{
  "to": "+14155550124",
  "whatsapp_template": {
    "name": "order_confirmation",
    "language": {"code": "de"},
    "components": [{
      "type": "body",
      "parameters": [{"type": "text", "text": "12345"}]
    }]
  }
}

Eine explizite Vorlage ersetzt den gespeicherten Standard und muss getrennt von Text und Medien-URLs versendet werden. Eine gespeicherte Standardvorlage ersetzt den freien Antworttext des Agenten. Registrierung und Genehmigung der Vorlage erfolgen bei Telnyx und WhatsApp.

Zustellstatus und Fehlerbehebung

Ein erfolgreicher ausgehender Verbindungs-Run speichert die Annahme durch Telnyx und die Nachrichten-ID. Prüfe die endgültige Zustellung in Telnyx. Die Annahme durch die API bestätigt noch keine Zustellung an den Empfänger.

• Fehlender Empfänger: Setze to, hinterlege einen Standardempfänger oder prüfe den passenden Eingangskontext für Antworten.
• Versand abgelehnt: Prüfe Anbieterfehler, Absenderregistrierung, Messaging-Profil, Kanallimits sowie die Genehmigung und Parameter einer Vorlage.
• Keine automatische Antwort: Prüfe die Outbound-Verknüpfung des Agenten, die ausgewählten Eingänge, die abschließende Ausgabe und den ausgehenden Verbindungs-Run.

Verbindungsfehler vor der Übermittlung und HTTP-429-Antworten können erneut versucht werden. Prüfe bei unklarem Ausgang nach Zeitüberschreitungen oder Serverfehlern vor einem erneuten Versand die Zustellung in Telnyx. Die erste Anfrage könnte bereits angenommen worden sein.