Tài liệu

Sổ tay cho AI agent

Gọi thoại qua trợ lý

Quay số hoặc nghe một cuộc gọi thoại Telegram 1:1 từ trợ lý AI, với tiếng phát ở tab trình duyệt sẵn sàng và người xác nhận trước khi đổ chuông.

Xem Markdown

Mục tiêu

Bạn bắt đầu, nghe, từ chối hoặc cúp một cuộc gọi thoại Telegram 1:1 thay cho người dùng. Bạn không mang tiếng: tiếng đi giữa máy chạy và một tab trình duyệt của người dùng.

Quyền cần

  • Phạm vi calls cho calls.start, calls.answer, calls.decline, calls.hangup, calls.endpoints.
  • messages.read cho calls.readiness, calls.list, calls.get.
  • Tài khoản phải nằm trong phạm vi kết nối. Phạm vi calls không có sẵn trong mẫu Vận hành hay Thiết lập: người dùng phải bật riêng hoặc chọn Toàn quyền.

Hỏi người trước khi

Cuộc gọi làm điện thoại của một người thật đổ chuông. Hỏi người dùng gọi ai, từ tài khoản nào, để làm gì. Không tự gọi chỉ vì có trong danh sách.

Kiểm trước

  1. Gọi whoami để chắc có phạm vi calls.
  2. Gọi calls.endpoints. Danh sách rỗng nghĩa là không có tab nào bật Sẵn sàng nhận cuộc gọi do Agent quay: nhờ người dùng mở app và bật công tắc này (ở trang Kết nối AI hoặc trong Cài đặt cuộc gọi). Không có tab thì calls.start trả audio_endpoint_required và không đổ chuông.
  3. Gọi calls.readiness với conversationId. Nếu ready là false, đọc mã lý do ở bảng dưới và dừng.

Các bước

  1. Gọi calls.start với conversationId. Lần đầu luôn trả confirmation_required kèm confirm_token.
  1. Nhận callId và theo dõi bằng operations_get cho việc quay số, rồi calls.get (hoặc sự kiện calls.*) cho trạng thái cuộc gọi: ringing → exchanging_keys → active → ended.
  2. Để nghe một cuộc gọi đến đang ringing, gọi calls.answer với callId; tiếng ra tab sẵn sàng. Nếu đã có người bấm nghe, bạn nhận already_answered.
  3. Gọi calls.hangup để kết thúc, hoặc calls.decline cho cuộc gọi đến chưa nghe. Hai thao tác này luôn chạy được và không tính hạn mức.

Kiểm sau

Đọc calls.get: state = ended và end_reason cho biết kết quả (hangup, remote_hangup, declined, missed, busy, failed, media_unreachable…). Chỉ báo người dùng "đã nói chuyện" khi cuộc gọi từng ở active và có thời lượng.

Khi lỗi

Mã Ý nghĩa Làm gì
proxy_no_udp Proxy của tài khoản không chở được tiếng (HTTP, hoặc SOCKS5 chưa xác nhận UDP) Báo người dùng cần proxy SOCKS5 có UDP; không thử lại
audio_endpoint_required Không có tab sẵn sàng Nhờ người dùng bật Sẵn sàng nhận cuộc gọi do Agent quay
account_unavailable Tài khoản chưa đăng nhập, tạm dừng, proxy lỗi hoặc máy tắt Dừng, báo người dùng
worker_outdated Máy chạy cũ hơn 1.0.49 Chờ máy tự cập nhật
not_private_chat Không phải chat riêng với một người Chọn chat riêng khác
peer_opted_out Người đó đã yêu cầu không liên hệ Không gọi
quota_exceeded Tài khoản An toàn đã đủ 10 cuộc hôm nay hoặc gọi quá sát nhau Chờ, không đổi tài khoản để lách
account_busy, node_calls_full Tài khoản hoặc máy đang đủ cuộc gọi Thử lại sau
calls_disabled Gọi đang tắt toàn hệ thống Chờ
already_answered, call_ended, call_not_found Cuộc gọi đã có người nghe, đã kết thúc hoặc không thuộc phạm vi Đọc lại calls.get

Kết thúc media_unreachable nghĩa là bắt máy được nhưng tiếng không qua được proxy. Không quay lại ngay; báo người dùng kiểm tra proxy.

Điều kiện dừng

Dừng khi cuộc gọi đã ended, khi người dùng không xác nhận, hoặc khi gặp bất kỳ mã lỗi nào ở trên ngoài account_busy / node_calls_full.