Telnyx Messaging

Im Code

Deklariere die Verbindungen in connectors/*.yaml. Setze Rufnummern und IDs in Anführungszeichen. Ohne sie liest YAML eine Nummer wie +14155550123 als Ganzzahl und das Deployment scheitert. Eine Inbound-Verbindung, die SMS empfängt:

type: telnyx_messaging
mode: inbound
connection: support-telnyx
config:
  channel: sms
  sender: "+14155550123"
agents:
  - messaging-assistant

Eine Outbound-Verbindung, die von derselben Nummer antwortet:

type: telnyx_messaging
mode: outbound
connection: support-telnyx
config:
  channel: sms
  sender: "+14155550123"
agents:
  - name: messaging-assistant
    outbound: { usage: automatic, source: [support-sms] }  # antwortet auf Runs der Inbound-Datei

Kontozugang

Ein Telnyx-Kontozugang enthält die Zugangsdaten des Kontos und kann beliebig viele Verbindungen für Telnyx Messaging und Telnyx Voice bedienen. Kanal und Absender gehören zu jeder einzelnen Verbindung. Mit dem API-Schlüssel listet connic Absender auf, setzt Webhooks und sendet Nachrichten; mit dem öffentlichen Schlüssel prüft connic die Signatur jedes Ereignisses von Telnyx. Änderst du den Kontozugang, erhalten alle seine Verbindungen die neuen Zugangsdaten.

Erzeugte Werte

connic setzt diese Werte beim Anlegen der Verbindung oder wenn sich der Absender ändert. Die Webhook-URL kopierst du aus dem Detailbereich. Sie gehören nicht in YAML-Dateien; connic lint lehnt sie ab.

Anhänge

connic lädt eingehende Medien herunter und übergibt sie unter files. Jede Datei hat name (etwa attachment-1.jpg), mime_type, Base64-kodierte data und size in Byte. Eine Nachricht nimmt bis zu 50 Dateien an, höchstens 32 MiB insgesamt.

Eine ungültige oder nicht abrufbare Datei lässt connic einzeln aus. Überschreitet eine Datei die Anzahl- oder Größengrenze, behält connic die Dateien davor und lässt diese und alle folgenden aus. file_issues nennt jede ausgelassene Datei mit code, Meldung und überschrittener Grenze, und die Logs der Verbindung erhalten eine Warnung. Der Run startet auch ohne angenommene Datei, außer Files required ist für die Verknüpfung des Agenten aktiviert. Der Agent sollte files und file_issues prüfen.

Gespräche

conversation_id bleibt gleich für jede Kombination aus Inbound-Verbindung, Kanal, Absender und Kunde. Damit der Verlauf über mehrere Nachrichten erhalten bleibt, setze session.key auf input.conversation_id und deploye den Agenten erneut; Sessions sind standardmäßig aus. Ist eine automatische Outbound-Verbindung verknüpft, wird die Textausgabe des Agenten zur Antwort.

version: "1.0"
name: messaging-assistant
description: "Beantwortet eingehende Telnyx-Nachrichten"
model: connic/gpt-5.6-terra
system_prompt: |
  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

Das Beispiel hält ein Gespräch 86.400 Sekunden lang. Die Session-Einstellungen beschreibt Agent YAML.

Gemeinsame Rufnummern

SMS und WhatsApp können dieselbe Nummer mit getrennten Inbound-Verbindungen und Agenten nutzen. Beide Verbindungen müssen denselben Kontozugang verwenden und teilen sich eine Webhook-URL; connic ordnet jede Nachricht anhand von Kanal und Empfänger zu. Löschst du eine der Verbindungen, bleibt der andere Kanal erreichbar. Zwei Inbound-Verbindungen können nicht denselben Kanal und Absender verwenden.

Externe WhatsApp-Nummern

Bei einer WhatsApp-Nummer, die nicht bei Telnyx gehostet ist, findet connic das Messaging-Profil nicht. Trage die Profil-ID in whatsapp_profile_id ein. connic prüft, ob das Profil zum Konto gehört, kann aber nicht bestätigen, dass die Nachrichten der Nummer über dieses Profil laufen. Outbound-Verbindungen für die Nummer brauchen dieselbe whatsapp_profile_id.

Kopiere nach dem Anlegen der Inbound-Verbindung den Incoming-message webhook aus dem Detailbereich. Trage ihn in Telnyx als primären Webhook dieses Messaging-Profils ein, wähle Webhook-API-Version 2 und stelle sicher, dass eingehende Nachrichten der Nummer über das Profil laufen. Der Webhook für Statusänderungen des WhatsApp Business Accounts ist eine separate Einstellung und leitet keine Nachrichten weiter.

Automatische Payload

Eine automatische Verknüpfung sendet die abschließende Ausgabe des Runs. Reiner Text wird zum Nachrichtentext. Ein JSON-Objekt kann die Felder der Agent-Tool-Payload unten enthalten; der Text darf auch in body, message, response oder output stehen.

Payload für Agent-Tool und Middleware

Das Modell oder die Middleware übergibt ein JSON-Objekt mit diesen Feldern. Unbekannte Felder führen zu einem Validierungsfehler. Eine Nachricht braucht Text, Medien oder eine Vorlage. Das Beispiel sendet ein WhatsApp-Bild mit Bildunterschrift:

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

• text: der Nachrichtentext. Bei reinen Mediennachrichten optional.
• to: der Empfänger; siehe Empfänger.
• media_urls: 1 bis 10 öffentliche Medien-URLs; siehe Medien.
• media_type: bei WhatsApp-Medien image, video, document, audio oder sticker.
• whatsapp_template: eine genehmigte Vorlage; siehe WhatsApp-Vorlagen.

Empfänger

connic sendet an den ersten Empfänger, den es findet:

1. to in der Payload oder in der automatischen Ausgabe.
2. Der Default recipient der Verbindung.
3. Bei einem Run, den eine Inbound-Verbindung für Telnyx Messaging gestartet hat, der Kunde, der die Nachricht gesendet hat. Beide Verbindungen müssen denselben Kontozugang, Kanal, Absender und dasselbe Messaging-Profil verwenden.

Ein Standardempfänger hat Vorrang vor Antworten; lass ihn leer, um jedem Kunden zu antworten. Findet connic keinen Empfänger, schlägt der Versand fehl.

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

• SMS/MMS: bis zu 10 Medien-URLs. Eine Nachricht mit Medien geht als MMS hinaus.
• WhatsApp: eine Medien-URL mit media_type. Bei Bildern, Videos und Dokumenten wird der Text zur Bildunterschrift; Audio und Sticker dürfen keinen Text enthalten.
• RCS: Text oder eine Medien-URL. Sende Text und Medien als getrennte Nachrichten.

WhatsApp-Vorlagen

Außerhalb des Kundenservice-Fensters von WhatsApp sendest du eine genehmigte Vorlage. Setze whatsapp_template als Standard an der Verbindung oder für eine einzelne Nachricht in der Payload. Bestimme die Vorlage über template_id oder über name und language.code. Optionale components vom Typ header, body oder button enthalten die Parameter im Telnyx-WhatsApp-Format.

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

Eine Vorlage in der Payload ersetzt den Standard der Verbindung und lässt sich nicht mit Text oder media_urls kombinieren. Solange die Verbindung eine Standardvorlage hat, nutzt jede Nachricht diese: Der Text des Agenten wird ignoriert, Medien-URLs werden abgelehnt. Vorlagen setzen den Kanal WhatsApp voraus. Registrierung und Genehmigung erfolgen bei Telnyx und WhatsApp.

Zustellung und Wiederholungen

Ein erfolgreicher Run der Verbindung bedeutet, dass Telnyx die Anfrage angenommen hat, nicht, dass die Nachricht zugestellt wurde. Die Ausgabe des Runs enthält die Nachrichten-ID von Telnyx; die endgültige Zustellung prüfst du in Telnyx.

connic wiederholt Verbindungsfehler vor der Übermittlung und 429-Antworten, wartet dabei so lange, wie Retry-After von Telnyx verlangt, und versucht es insgesamt 3-mal. Andere Fehler werden nicht wiederholt. Ist das Ergebnis unklar, etwa nach einer Zeitüberschreitung oder einer 5xx-Antwort, prüfe Telnyx, bevor du erneut sendest; Telnyx hat die Nachricht womöglich schon angenommen.