Twilio Messaging

So funktionieren eingehende Nachrichten

Twilio sendet die Nachricht als signierten HTTP POST mit Formulardaten an den Webhook der Verbindung. Connic prüft die Anfrage, bereitet die Eingabe auf und legt einen Run pro verknüpftem Agenten an. Der Webhook gibt eine leere TwiML-Antwort zurück. Antworten an den Kunden versendet eine separate Outbound-Verbindung.

Eingehende und ausgehende Verbindungen können denselben gespeicherten Twilio-Kontozugang wie Twilio Voice verwenden. Er enthält Account SID, Region und den Auth Token dieser Region. Kanal und Absender werden für jede Verbindung einzeln festgelegt.

Inbound einrichten

1. 1

   Twilio-Absender vorbereiten

   Verwende eine Twilio-Rufnummer mit Messaging-Unterstützung oder einen registrierten WhatsApp- oder RCS-Absender. Entferne einen bestehenden Webhook für eingehende Nachrichten oder eine zugewiesene TwiML-App, bevor du den Absender Connic zuordnest. Gehört der Absender zu einem Messaging Service, wähle dort für eingehende Nachrichten Defer to sender's webhook. Aktiviere für einen WhatsApp-Test die Twilio Sandbox und tritt ihr mit dem Testtelefon bei.

2. 2

   Eingehende Verbindung anlegen

   Füge Twilio Messaging aus dem Marktplatz hinzu und wähle Inbound. Wähle einen gespeicherten Twilio-Kontozugang oder lege einen mit Account SID, Region und regionalem Auth Token an. Wähle den Kanal und anschließend den Twilio-Absender aus der Auswahlliste. Speichere die Verbindung. Connic richtet den Webhook für eingehende Nachrichten bei SMS/MMS-Rufnummern und registrierten WhatsApp- und RCS-Absendern automatisch in Twilio ein. Fehler bei der Einrichtung erscheinen beim Speichern.

3. 3

   Nur WhatsApp Sandbox: Webhook in Twilio eintragen

   Für die Sandbox ist ein manueller Schritt nötig, da Twilio keine dokumentierte öffentliche API zum Ändern ihres Webhooks bereitstellt. Wähle WhatsApp Sandbox in Connic, speichere und kopiere Incoming-message webhook aus den Verbindungsdetails. Trage die exakte URL in Twilios Sandbox settings unter When a Message Comes in ein, wähle HTTP POST und speichere. Details stehen in Twilios Anleitung für Sandbox-Webhooks.

4. 4

   Agenten verknüpfen und testen

   Verknüpfe die aktivierte Verbindung mit einem bereitgestellten Agenten. Sende eine Nachricht an den konfigurierten Absender und prüfe die Run-Eingabe. Für automatische Antworten wird zusätzlich eine Outbound-Verbindung mit demselben Twilio-Kontozugang, Kanal und Absender benötigt.

Beim Absenderwechsel richtet Connic den neuen Absender ein. Der bisherige Webhook wird nur entfernt, wenn er noch auf diese Verbindung zeigt. Dasselbe gilt beim Löschen der eingehenden Verbindung. Die Sandbox-Einstellungen müssen beim Wechsel zu einem anderen Absender oder beim Löschen ihrer Verbindung manuell angepasst werden. Die Voice-Einstellungen der Rufnummer bleiben unverändert.

Inbound-Konfiguration

• Twilio-Kontozugang: Gespeichertes Konto mit regionalen Zugangsdaten, das auch andere Twilio-Verbindungen verwenden können.
• Kanal: SMS / MMS, WhatsApp oder RCS. Für jeden Kanal und Absender wird eine eigene Verbindung angelegt.
• Twilio-Absender: Wähle die empfangende Rufnummer oder den Kanalabsender aus dem verbundenen Konto. Er muss mit der To-Adresse im Webhook übereinstimmen.
• Incoming-message webhook: Wird beim Speichern automatisch erzeugt und in Twilio eingetragen. Für die WhatsApp Sandbox gilt der manuelle Schritt oben.

Eingabe des Agenten

Der Agent erhält normalisierte Adressen und den Nachrichtentext auf oberster Ebene. raw enthält die ursprünglichen Twilio-Formularfelder einschließlich kanalspezifischer Angaben, sofern Twilio sie übermittelt. Das Beispiel zeigt eine WhatsApp-Nachricht ohne Anhänge.

{
  "message_sid": "SM00000000000000000000000000000001",
  "channel": "whatsapp",
  "from": "whatsapp:+14155550124",
  "to": "whatsapp:+14155550123",
  "text": "Was ist der Status von Bestellung 12345?",
  "conversation_id": "twilio_messaging:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091",
  "raw": {
    "AccountSid": "AC00000000000000000000000000000000",
    "MessageSid": "SM00000000000000000000000000000001",
    "From": "whatsapp:+14155550124",
    "To": "whatsapp:+14155550123",
    "Body": "Was ist der Status von Bestellung 12345?",
    "NumMedia": "0"
  }
}

Eingehende Medien

Connic lädt eingehende Anhänge herunter und übergibt sie im üblichen Eingabeformat 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. Medien erfordern einen US1-Kontozugang.

Kann ein Anhang nicht heruntergeladen werden oder überschreitet er das Limit, lehnt Connic den Webhook ab. Der Agent startet dann nicht mit unvollständigen Dateien. Bei einer Nachricht, die nur Medien enthält, kann text leer sein; der Agent sollte auch files berücksichtigen.

Gesprächsverlauf und Beispielagent

Die stabile conversation_id unterscheidet Gespräche nach eingehender Verbindung, Konto, Region, Kanal, Twilio-Absender und Kunden. Setze für einen fortlaufenden Gesprächsverlauf session.key auf input.conversation_id und stelle den Agenten erneut bereit. Sessions werden nicht automatisch aktiviert.

name: messaging-assistant
model: connic/gpt-5.6-terra
system: |
  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 setzt die Session-TTL auf 86.400 Sekunden. Ist eine automatische Outbound-Verbindung verknüpft, wird die Textausgabe des Agenten als Antwort versendet. Die Session-Einstellungen beschreibt Agent YAML.

Fehler bei eingehenden Nachrichten

• Speichern scheitert an der Webhook-Einrichtung: Behebe den angezeigten Twilio-Fehler. Entferne einen bestehenden Webhook für eingehende Nachrichten oder eine TwiML-App. Falls ein Messaging Service den Absender verwaltet, wähle dort Defer to sender's webhook und speichere erneut.
• Twilio sendet die Demo-Antwort der Sandbox: Speichere die Connic-URL mit HTTP POST unter When a Message Comes in in den Sandbox-Einstellungen. Das Aktivieren der Verbindung in Connic ersetzt diesen Sandbox-Schritt nicht.
• Kein Agenten-Run: Prüfe die aktivierte Verbindung, das verknüpfte Deployment, die exakte POST-Webhook-URL und die Twilio-Einstellungen für eingehende Nachrichten.
• Signatur- oder Kontofehler: Prüfe Account SID, Region und regionalen Auth Token des gewählten Kontozugangs. Die URL in Twilio muss mit der erzeugten URL übereinstimmen.
• Falscher Kanal oder Empfänger: Gleiche Kanal und Absender der Verbindung mit der To-Adresse der Nachricht ab.
• Fehler beim Anhang: Prüfe den Fehler im Verbindungs-Run und die Twilio-Logs. Die Medien müssen verfügbar sein und zusammen unter dem Downloadlimit liegen.

So funktionieren ausgehende Nachrichten

Automatische Outbound-Verbindungen senden die abschließende Ausgabe eines Runs und lassen sich auf ausgewählte eingehende Verbindungen beschränken. Agent-Tool- und Middleware-Verbindungen senden bei einem Aufruf. Connic ermittelt den Empfänger und übermittelt die Nachricht mit den gespeicherten Zugangsdaten an Twilios Messaging-API.

Outbound einrichten

1. 1

   Kontozugang und Absender auswählen

   Lege eine Twilio-Messaging-Verbindung im Outbound-Modus an. Wähle den Twilio-Kontozugang und den Kanal, anschließend einen Absender aus der Auswahlliste des Kontos. Den Kontozugang kann auch Twilio Voice verwenden. Für Antworten müssen Kontozugang, Kanal und Absender mit der eingehenden Verbindung übereinstimmen.

2. 2

   Empfänger und optionale Vorgaben festlegen

   Trage für Benachrichtigungen einen Standardempfänger ein. Für Antworten auf eingehende Nachrichten bleibt er leer. Optional können eine Messaging Service SID, die den Absender enthält, eine Content Template SID als Standard und Vorlagenvariablen hinterlegt werden. Speichere die Verbindung.

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. Ein reiner Benachrichtigungsablauf benötigt einen Standardempfänger oder ein ausdrückliches to im Payload.

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 Twilios Messaging Logs nach der zurückgegebenen Message SID, um den Zustellstatus zu sehen.

Outbound-Konfiguration

• Twilio-Kontozugang, Kanal und Absender: Für jeden Versand erforderlich. Adressformate und Regionen stehen in der Übersicht unter den Tabs.
• Standardempfänger: Optionale Zieladresse, die gilt, wenn to im Payload fehlt.
• Messaging Service SID: Optionale MG…-Kennung, die zusätzlich zum konfigurierten Absender übermittelt wird.
• Content Template SID als Standard: Optionale HX…-Kennung einer in Twilio erstellten Vorlage.
• Standardvariablen: JSON-Objekt mit Zeichenketten als Werten, etwa {"1": "Alex"}. Dafür muss eine Vorlagen-SID hinterlegt sein.

Payload für ausgehende Nachrichten

Automatische Outbound-Verbindungen akzeptieren reinen Text oder ein JSON-Objekt. Agent-Tool- und Middleware-Verbindungen verwenden das unten gezeigte JSON-Objekt. Der Toolname einer Agent-Tool-Verbindung ist editierbar und lautet standardmäßig send_to_<connector_name>. Middleware ruft den konfigurierten Verbindungsnamen über send_connector auf.

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

Unterstützt werden text, to, media_urls, content_sid und content_variables. Text ist auf 1.600 Zeichen begrenzt. Die Nachricht muss Text, Medien oder eine Vorlage enthalten; bei reinen Mediennachrichten ist Text optional. to kann entfallen, wenn ein Standardempfänger oder der passende Kontext einer Eingangsnachricht das Ziel vorgibt.

Medien versenden

Übergib in media_urls öffentliche HTTP- oder HTTPS-URLs ohne eingebettete Zugangsdaten. Twilio ruft die Dateien ab. Connic akzeptiert bis zu 10 URLs für MMS und eine für WhatsApp oder RCS. IE1 unterstützt ausschließlich SMS-Text. Für ausgehende Medien werden URLs verwendet, nicht das Base64-Format unter files aus eingehenden Nachrichten.

Die Dateitypen und Größenlimits des jeweiligen Kanals gelten weiterhin. WhatsApp ignoriert Text, der zusammen mit Audio, Video, Dokumenten oder anderen Medien außer Bildern versendet wird. Sende Text und diese Medien getrennt. Details stehen in Twilios Referenz zum WhatsApp-Versand.

WhatsApp-Vorlagen

Außerhalb des 24-Stunden-Servicefensters von WhatsApp ist eine genehmigte Vorlage erforderlich. Erstelle sie in Twilio und lasse sie dort genehmigen. Hinterlege anschließend Content SID und Variablen in der Verbindung oder übergib sie im Payload. Die Schritte beschreibt Twilios Anleitung für Nachrichtenvorlagen.

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

Payload-Werte überschreiben die gespeicherte Content SID und das Variablenobjekt. Variablenwerte müssen Zeichenketten sein. Vorlagen verwenden Variablen anstelle von text oder media_urls; die ausdrückliche Kombination einer Vorlage mit diesen Feldern wird abgelehnt. Ist eine Content SID in der Verbindung hinterlegt, wird reiner generierter Text ignoriert. Gib content_variables zurück, um die Vorlage zu füllen.

Zustellstatus und Fehlerbehebung

Ein erfolgreicher ausgehender Verbindungs-Run bedeutet, dass Twilio die API-Anfrage angenommen hat. Die Zustellung ist damit nicht bestätigt. Das Ergebnis enthält die Message SID und verfügbare Statusfelder. Twilios Messaging Logs zeigen den Zustellstatus und kanalspezifische Fehler.

• Fehlender Empfänger: Setze to, hinterlege einen Standardempfänger oder prüfe, ob eingehende und ausgehende Verbindung die erforderlichen Konto- und Absenderangaben teilen.
• Versand abgelehnt: Prüfe Twilio-Fehlercode, Absenderregistrierung, Kanaladresse, regionale Unterstützung sowie Vorlagengenehmigung und Variablen.
• Keine automatische Antwort: Prüfe die Outbound-Verknüpfung des Agenten und die ausgewählten Eingänge, anschließend das Agentenergebnis und den ausgehenden Verbindungs-Run.

Connic stuft Verbindungsfehler vor der Übermittlung und HTTP-429-Antworten als wiederholbar ein. Bei ungewissem Übermittlungsergebnis, etwa nach Lese-, Schreib- oder Serverfehlern, müssen vor einem erneuten Versand die Twilio-Logs geprüft werden. Eine bereits angenommene Anfrage könnte sonst zu einer doppelten Nachricht führen.