Cách kết nối kênh văn bản bên ngoài với ElevenLabs agent thông qua webhook

Kết nối kênh văn bản bên ngoài với ElevenLabs agent thông qua webhook

Tổng quan

Kênh tùy chỉnh (Custom Channel) cho phép kết nối một hệ thống nhắn tin bên ngoài với một ElevenLabs agent. Bạn có thể gửi tin nhắn của người dùng đến webhook của ElevenLabs, sau đó nhận phản hồi từ agent thông qua endpoint HTTPS của riêng bạn.

Các tính năng

Thiết lập

1. Mở kênh tùy chỉnh (Custom Channel)

Truy cập vào agent của bạn, chọn Channels, nhấn Custom Channel, rồi nhấp vào Add trigger.

2. Cấu hình trình kích hoạt

Chọn một kết nối hiện có hoặc tạo mới, sau đó nhập Reply Webhook URL.

3. Sao chép thông tin xác thực

Nhấp vào Add, sau đó sao chép Inbound Webhook URL, Inbound Secret và Outbound Signing Secret.

4. Cấu hình dịch vụ của bạn

Gửi tin nhắn của người dùng đến URL Webhook đầu vào, kèm theo mã bí mật đầu vào trong tiêu đề X-Webhook-Secret. Sử dụng outbound signing secret để xác thực từng phản hồi.

Gửi tin nhắn

Gửi yêu cầu POST tới URL Webhook đã tạo:

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 trả về mã phản hồi 202 Accepted trước khi xử lý lượt tương tác:

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

Để tiếp tục cuộc trò chuyện, hãy gửi một yêu cầu khác kèm theo conversation_id đó cùng với một user_message_id mới.

Nhận phản hồi

ElevenLabs sẽ gửi một yêu cầu POST tới URL webhook phản hồi sau mỗi lượt trao đổi:

{
  "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
}

Nếu quá trình xử lý thất bại, status là failed, data là [], và error chứa mô tả.

data liệt kê các sự kiện theo thứ tự lượt. Mỗi mục có một type và một event:

• agent_response chứa một câu nói của agent. response_id xác định duy nhất câu nói, trong khi event_id liên kết nó với một lượt. Kết hợp các giá trị agent_response nếu kênh của bạn hiển thị một bong bóng văn bản cho mỗi lượt.
• agent_tool_response báo cáo kết quả của công cụ và chia sẻ event_id của lượt đó. Trạng thái của nó là thành công, lỗi, bị chặn hoặc bị bỏ qua. Một phản hồi với tool_type: "system", tool_name: "end_call" và status: "success" có nghĩa là agent đã kết thúc cuộc trò chuyện.

Nhiều tin nhắn đến có thể được gộp lại thành một lượt. user_message_ids liệt kê các ID tin nhắn người dùng mà phản hồi này đang trả lời.

Xác minh chữ ký phản hồi

Mỗi phản hồi bao gồm tiêu đề ElevenLabs-Signature:

t=1753876800,v0=<hex-digest>

Mã hash là chữ ký HMAC-SHA256 trên {timestamp}.{raw_request_body} sử dụng outbound signing secret. Xác minh nội dung thô trước khi phân tích cú pháp JSON và từ chối các timestamp lỗi thời.

Python

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")

TypeScript

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySignature(rawBody: Buffer, header: string, secret: string): void {
  const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  const timestamp = values.t;
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 30 * 60) {
    throw new Error("Stale webhook signature");
  }

  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  const received = Buffer.from(values.v0 ?? "", "hex");
  if (received.length !== expected.length || !timingSafeEqual(expected, received)) {
    throw new Error("Invalid webhook signature");
  }
}

Cơ chế gửi dữ liệu

ElevenLabs thực hiện 3 lần gửi dữ liệu trong quá trình xử lý, vào các thời điểm khoảng 0, 0,5 và 2 giây. Phản hồi thuộc nhóm 2xx được coi là gửi thành công.

Phần thân yêu cầu (request body) bị giới hạn ở mức 256 KiB.