REST API & webhook Team

Trang này dành cho ai. Trang này dành cho lập trình viên và bộ phận IT. REST API cho phép phần mềm của riêng bạn khởi động ScribX trong cuộc họp và đọc bản phiên âm cũng như bản ghi. Webhook cho phép ScribX gửi thông báo đến hệ thống của bạn khi có sự kiện xảy ra, ví dụ khi cuộc họp kết thúc hoặc bản tóm tắt đã sẵn sàng. Nếu bạn không chuyên về kỹ thuật, hãy gửi trang này cho bộ phận IT. Để kết nối lịch, Zoom hoặc Notion mà không cần viết mã, hãy xem Tích hợp.

Gói

REST API, webhook và khóa API được hỗ trợ trên gói Team và Enterprise. Xem Gói & thanh toán.

Tích hợp → API. Các khóa hoạt động với tư cách của bạn, cho không gian riêng của bạn hoặc cho một nhóm.

Những việc bạn có thể làm với API

• Khởi động ScribX trong cuộc họp. Gửi đường dẫn cuộc họp, và ScribX sẽ tham gia cuộc họp đó.
• Liệt kê các cuộc họp và đọc thông tin chi tiết cùng trạng thái của chúng.
• Đọc bản phiên âm. Mỗi dòng có tên người nói và mốc thời gian.
• Lấy bản ghi của cuộc họp, khi cuộc họp có lưu âm thanh hoặc video.
• Liệt kê người tham gia của một cuộc họp.

Bản tóm tắt được gửi đến bạn qua webhook summary.update (xem bên dưới), hoặc qua máy chủ MCP.

Tạo khóa API

1. Trong ứng dụng web, tại thanh bên, trong mục Khác, nhấp vào Tích hợp.
2. Trong mục Nâng cao, nhấp vào API.
3. Ở phía trên, nhấp vào Cá nhân (chỉ các cuộc họp trong không gian riêng của bạn) hoặc Nhóm (các cuộc họp của một nhóm).
4. Nhấp vào Khóa mới.
5. Trong ô Tên, nhập tên cho biết khóa được dùng ở đâu, ví dụ "Production".
6. Trong mục Phạm vi, chọn những việc khóa được phép làm. Nếu bạn không đánh dấu ô nào, khóa sẽ có toàn quyền truy cập:
   • bots:read: đọc các cuộc họp và trạng thái của chúng.
   • bots:write: khởi động và điều khiển ScribX trong cuộc họp.
   • recordings:read: đọc bản ghi và bản phiên âm.
   • webhooks:write: quản lý webhook.
7. Nhấp vào Tạo khóa.
8. Sao chép khóa ngay. Khóa chỉ hiển thị một lần. Hãy lưu khóa ở nơi an toàn, chẳng hạn trình quản lý mật khẩu. Gửi khóa cho lập trình viên qua kênh bảo mật, không gửi trong tin nhắn trò chuyện thông thường.

Khóa hoạt động với tư cách của bạn. Khóa chỉ mở được những gì bạn có quyền mở. Chỉ bạn nhìn thấy khóa trong danh sách. Để khóa ngừng hoạt động, nhấp vào Thu hồi khóa bên cạnh khóa đó. Mọi thứ sử dụng khóa sẽ ngừng hoạt động ngay lập tức.

Gọi API

Gửi khóa trong header Authorization, với từ Token đứng trước:

curl https://platform.scribx.app/api/v1/bots \
  -H "Authorization: Token YOUR_API_KEY"

Các địa chỉ chính (tất cả nằm dưới https://platform.scribx.app/api/v1/):

Địa chỉ	Chức năng
POST bots	Khởi động ScribX trong cuộc họp.
GET bots	Liệt kê các cuộc họp.
GET bots/{id}	Thông tin chi tiết và trạng thái của một cuộc họp.
GET bots/{id}/transcript	Bản phiên âm.
GET bots/{id}/recording	Đường dẫn tải bản ghi.
GET bots/{id}/participants	Những người tham gia.

Để có tài liệu tham chiếu đầy đủ, hãy liên hệ bộ phận hỗ trợ ScribX.

Webhook

Webhook là một địa chỉ web trong hệ thống của bạn. ScribX gửi một thông báo (HTTP POST) đến địa chỉ đó mỗi khi một sự kiện xảy ra.

Thêm webhook

1. Mở Tích hợp. Trong mục Nâng cao, nhấp vào Webhooks.
2. Ở phía trên, nhấp vào Cá nhân hoặc Nhóm.
3. Trong mục Khoá ký, nhấp vào Sao chép khoá ký. ScribX ký mọi thông báo bằng khoá này. Hệ thống của bạn dùng khoá để kiểm tra thông báo có thực sự đến từ ScribX hay không. Tất cả địa chỉ webhook của bạn dùng chung một khoá.
4. Nhấp vào Thêm webhook.
5. Trong ô URL điểm cuối, nhập địa chỉ hệ thống của bạn. Địa chỉ phải bắt đầu bằng https://.
6. Trong mục Sự kiện, chọn một hoặc nhiều sự kiện. Các sự kiện hữu ích nhất là:
   • bot.state_change: ScribX đã tham gia, đã rời đi, hoặc cuộc họp đã kết thúc.
   • transcript.update: có dòng phiên âm mới.
   • summary.update: bản tóm tắt đã được viết xong. Nội dung tóm tắt nằm trong thông báo.
   • participant_events.join_leave: có người tham gia hoặc rời cuộc họp.
7. Nhấp vào Thêm webhook.

Nội dung ScribX gửi

Mỗi thông báo có định dạng JSON, như sau:

{
  "idempotency_key": "…",      // unique for each message
  "bot_id": "bot_…",           // the meeting
  "bot_metadata": { },
  "trigger": "summary.update", // the event
  "data": { }                  // the event's details
}

Chữ ký nằm trong header X-Webhook-Signature.

Dành cho lập trình viên

Phản hồi bằng mã trạng thái 2xx trong vòng 10 giây, sau đó mới xử lý các tác vụ tốn thời gian. Nếu hệ thống của bạn phản hồi bằng mã khác hoặc không phản hồi kịp thời, ScribX sẽ gửi lại thông báo. Dùng idempotency_key để bỏ qua thông báo bạn đã xử lý.

Bước tiếp theo

• Máy chủ MCP
• Tích hợp