Tài liệu

Sổ tay cho AI agent

Gửi một tin nhắn an toàn

Gửi một nội dung đã được phép tới một người, chống trùng và theo dõi kết quả qua cổng an toàn.

Xem Markdown

Mục tiêu

Bạn gửi một tin tới đúng một người bằng tài khoản đã được cấp. Một lời gọi được chấp nhận chỉ có nghĩa là công việc đã được tạo, chưa phải Telegram đã xác nhận gửi thành công.

Quyền cần

  • messages.read để đọc hội thoại và ngữ cảnh.
  • messages.send để giữ hội thoại và gửi.
  • accounts.read nếu cần kiểm tra tài khoản trước khi gửi.
  • crm.read nếu cần đọc hồ sơ khách và thông tin không liên hệ.

Không cần quyền quản lý kết nối hoặc đổi hạn mức để gửi một tin bình thường.

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

Xác nhận người nhận, tài khoản gửi, nội dung và mục đích. Nếu đã có uỷ quyền rõ cho loại câu trả lời này, làm trong phạm vi đó; nội dung ngoài phạm vi phải hỏi lại.

Không suy diễn sự đồng ý từ việc người nhận tồn tại trong CRM. Không tự đổi tài khoản gửi khi tài khoản đã chọn bị chặn.

Kiểm trước

Gọi whoami. Đọc hội thoại bằng conversations_get và tin gần nhất bằng messages_list.

Kiểm tra không liên hệ khi có dữ liệu; cổng an toàn vẫn quyết định ở lúc giao việc. Giữ hội thoại bằng conversations_claim, không dùng force để giành khoá.

Đọc schema messages.send bằng tools_describe, nhất là các trường định danh tin, điều kiện tin mới nhất và nội dung gửi.

Các bước

  1. Xác định một định danh bền vững cho ý định gửi.
  2. Chốt payload cho ý định đó.
  3. Nếu dùng REST, gửi Idempotency-Key theo hợp đồng thao tác.
  4. Nếu hợp đồng gửi có clientMessageId, giữ nguyên giá trị đó khi gửi lại cùng ý định.
  5. Đặt ifLastMessageId khi câu trả lời chỉ còn phù hợp nếu khách chưa nhắn thêm.
  1. Gọi MCP messages_send, hoặc REST operation messages.send.
  2. Lưu ID thao tác trả về.
  3. Gọi operations_get để theo dõi.
  4. Nhả hội thoại bằng conversations_release khi kết thúc xử lý.

Với REST, phần xác thực dùng:

Authorization: Bearer $TELEGRAM_AUTO_API_KEY
Idempotency-Key: reply-demo-event-a

Không tự giả định tools_run có một tham số idempotency ngoài schema. Đọc đúng hợp đồng và dùng cơ chế định danh tin được thao tác hỗ trợ.

Kiểm sau

Chỉ báo gửi thành công khi trạng thái đã xác nhận. Nếu mất kết nối sau lời gọi, tra thao tác cũ hoặc gửi lại đúng định danh và payload; không tạo khoá mới chỉ vì chưa nhận phản hồi.

Cùng định danh nhưng nội dung khác có thể bị từ chối xung đột. Muốn đổi nội dung, đọc lại ngữ cảnh và quyết định đó có phải một ý định gửi mới thực sự hay không.

Khi lỗi

  • 409: đọc mã lỗi cụ thể; có thể là xung đột định danh, khoá hội thoại hoặc ngữ cảnh đã cũ. Không thử lại nguyên xi mọi lỗi 409.
  • 429: chờ theo thời gian phản hồi; không đổi kết nối để né giới hạn.
  • held: theo dõi lý do giữ và thao tác hiện có; không tạo bản sao.
  • confirmation_required: trình bày yêu cầu cho người và chờ quyết định.
  • outcome_unknown hoặc unverified: đối soát, không gửi lại mù.

Điều kiện dừng

Dừng khi có không liên hệ, khoá của người khác, quyền bị thu hồi, nội dung vượt uỷ quyền hoặc kết quả chưa rõ.

Xem điều tra việc lỗi và hạn mức Telegram.