Benutzerdefinierter Kanal

Übersicht

Custom Channel verbindet ein externes Nachrichtensystem mit einem ElevenLabs-Agenten. Senden Sie Nutzernachrichten an einen ElevenLabs-Webhook und erhalten Sie Agentenantworten an Ihrem eigenen HTTPS-Endpunkt.

Funktionen

Einrichtung

Nachricht senden

Senden Sie eine POST-Anfrage an die generierte Webhook-URL:

POST /v1/convai/api-integrations/custom_channel/triggers/{trigger_connection_id}/async_message
X-Webhook-Secret: <inbound-secret>
Content-Type: application/json

{
  "data": {
    "type": "user_message",
    "text": "Where is my order?",
    "user_identifier": "customer_8427"
  },
  "user_message_id": "msg_01k1e6z3f4t8n9c2",
  "dynamic_variables": {
    "order_id": "order_72491"
  }
}

ElevenLabs gibt vor der Verarbeitung des Gesprächszugs 202 Accepted zurück:

{
  "conversation_id": "conv_01k1e72d4x8p6v3m",
  "status": "queued"
}

Um das Gespräch fortzusetzen, senden Sie eine weitere Anfrage mit dieser conversation_id und einer neuen user_message_id.

Antworten empfangen

ElevenLabs sendet nach jedem Gesprächszug eine POST-Anfrage an die Reply-Webhook-URL:

{
  "version": "1",
  "conversation_id": "conv_01k1e72d4x8p6v3m",
  "user_message_ids": ["msg_01k1e6z3f4t8n9c2"],
  "status": "completed",
  "data": [
    {
      "type": "agent_response",
      "event": {
        "agent_response": "Your order is scheduled to arrive tomorrow.",
        "response_id": "9f2c1a7e-4b3d-4e8a-9c1f-2d6b8e0a5f31",
        "event_id": 4
      }
    },
    {
      "type": "agent_tool_response",
      "event": {
        "tool_name": "end_call",
        "tool_call_id": "toolu_01k1e70r4b8y",
        "tool_type": "system",
        "event_id": 4,
        "is_called": true,
        "is_error": false,
        "is_blocked": false,
        "status": "success"
      }
    }
  ],
  "error": null
}

Wenn die Verarbeitung fehlschlägt, ist status gleich failed, data gleich [] und error enthält eine Beschreibung.

data führt Ereignisse in der Reihenfolge des Gesprächszugs auf. Jedes Element hat einen type und ein event:

• agent_response enthält eine Agentenäußerung. response_id identifiziert die Äußerung eindeutig, während event_id sie einem Gesprächszug zuordnet. Führen Sie die agent_response-Werte zusammen, wenn Ihr Kanal pro Gesprächszug eine Textblase darstellt.
• agent_tool_response meldet das Ergebnis eines Tools und verwendet dieselbe event_id wie der Gesprächszug. Sein status ist success, error, blocked oder skipped. Eine Antwort mit tool_type: "system", tool_name: "end_call" und status: "success" bedeutet, dass der Agent das Gespräch beendet hat.

Mehrere eingehende Nachrichten können zu einem Gesprächszug zusammengefasst werden. user_message_ids führt die IDs der Nutzernachrichten auf, die diese Antwort beantwortet.

Antwortsignaturen verifizieren

Jede Antwort enthält einen ElevenLabs-Signature-Header:

t=1753876800,v0=<hex-digest>

Der Digest ist eine HMAC-SHA256-Signatur über {timestamp}.{raw_request_body} unter Verwendung des Outbound Signing Secret. Verifizieren Sie den Rohtext vor dem Parsen von JSON und lehnen Sie veraltete Zeitstempel ab.

import hashlib
import hmac
import time
def verify_signature(raw_body: bytes, header: str, secret: str) -> None:
    values = dict(part.split("=", 1) for part in header.split(","))
    timestamp = values["t"]
    if abs(time.time() - int(timestamp)) > 30 * 60:
        raise ValueError("Stale webhook signature")
    expected = hmac.new(
        secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(expected, values["v0"]):
        raise ValueError("Invalid webhook signature")

Zustellverhalten

ElevenLabs unternimmt drei Zustellversuche im Prozess nach ungefähr 0, 0,5 und 2 Sekunden. Eine 2xx-Antwort markiert die Zustellung als erfolgreich.

Anfrage-Bodys sind auf 256 KiB begrenzt.