Twilio 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 WhatsApp-Nachrichten empfängt:

type: twilio_messaging
mode: inbound
connection: support-twilio
config:
  channel: whatsapp
  sender: "whatsapp:+14155550123"
agents:
  - messaging-assistant

Eine Outbound-Verbindung, die vom selben Absender antwortet:

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

Kontozugang

Ein Twilio-Kontozugang enthält die Zugangsdaten des Kontos und kann beliebig viele Verbindungen für Twilio Messaging und Twilio Voice bedienen. Kanal und Absender gehören zu jeder einzelnen Verbindung. Mit den Zugangsdaten listet connic Absender auf, setzt Webhooks und sendet Nachrichten; mit dem Auth Token prüft connic die Signatur jeder Anfrage von Twilio.

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 (die Twilio-Media-SID mit Dateiendung), mime_type, Base64-kodierte data und size in Byte. Eine Nachricht nimmt bis zu 50 Dateien an, höchstens 32 MiB insgesamt. Downloads setzen einen US1-Kontozugang voraus.

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, Konto, Region, 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 Twilio-Nachrichten"
model: connic/gpt-5.6-terra
system_prompt: |
  Beantworte die eingehende Nachricht klar und knapp.
  Frage nach fehlenden Angaben, statt Annahmen zu treffen.
  Gib die Antwort als reinen 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.

WhatsApp Sandbox

Für den Webhook der Sandbox bietet Twilio keine dokumentierte öffentliche API, deshalb trägst du ihn selbst ein. Lege die Verbindung mit dem Kanal WhatsApp und dem Absender WhatsApp Sandbox (activation required) an und kopiere den Incoming-message webhook aus dem Detailbereich. Füge die exakte URL in den Sandbox-Einstellungen von Twilio unter When a Message Comes in ein, wähle HTTP POST und speichere; siehe Twilios Anleitung für Sandbox-Webhooks. Wechselt die Verbindung zu einem anderen Absender oder löschst du sie, passt du die Sandbox-Einstellungen selbst an.

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.

{
  "text": "Deine Bestellung wurde verschickt.",
  "to": "whatsapp:+14155550124",
  "media_urls": ["https://example.com/shipping-label.png"]
}

• text: der Nachrichtentext, höchstens 1.600 Zeichen. Bei reinen Mediennachrichten optional.
• to: der Empfänger; siehe Empfänger.
• media_urls: 1 bis 10 öffentliche Medien-URLs; siehe Medien.
• content_sid und content_variables: eine Vorlage und ihre Variablen; 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 Twilio Messaging gestartet hat, der Kunde, der die Nachricht gesendet hat. Beide Verbindungen müssen denselben Kontozugang, Kanal und Absender 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; Twilio ruft die Dateien ab. Eine Nachricht nimmt bis zu 10 URLs für MMS und eine für WhatsApp oder RCS an. In IE1 geht nur Text. Ausgehende Medien verwenden URLs, nicht das Base64-Format unter files aus eingehenden Nachrichten.

Es gelten die Dateitypen und Größengrenzen des jeweiligen Kanals. WhatsApp ignoriert Text, der zusammen mit Audio, Video, Dokumenten oder anderen Medien außer Bildern gesendet wird; sende diesen Text als eigene Nachricht. Siehe Twilios Referenz zum WhatsApp-Versand.

WhatsApp-Vorlagen

Außerhalb des 24-Stunden-Servicefensters von WhatsApp sendest du eine genehmigte Vorlage. Erstelle die Vorlage in Twilio und lass sie dort genehmigen; hinterlege dann ihre Content SID und Variablen an der Verbindung oder übergib sie in der Payload. Siehe Twilios Anleitung für Nachrichtenvorlagen.

{
  "to": "whatsapp:+14155550124",
  "content_sid": "HX00000000000000000000000000000000",
  "content_variables": {"1": "12345", "2": "Freitag"}
}

Werte aus der Payload überschreiben content_sid und content_variables der Verbindung. Variablenwerte müssen Strings sein. Eine Payload mit content_sid darf nicht zugleich Text oder media_urls enthalten. Solange die Verbindung eine Standard-Content-SID hat, nutzt jede Nachricht die Vorlage: Reiner Text des Agenten wird ignoriert, Medien-URLs werden abgelehnt. Gib content_variables zurück, um die Vorlage zu füllen.

Zustellung und Wiederholungen

Ein erfolgreicher Run der Verbindung bedeutet, dass Twilio die Anfrage angenommen hat, nicht, dass die Nachricht zugestellt wurde. Die Ausgabe des Runs enthält die Message SID und die Statusfelder, die Twilio zurückgegeben hat; Zustellstatus und Kanalfehler zeigen die Messaging Logs von Twilio.

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