---
title: "Gửi một tin nhắn an toàn"
locale: vi
url: https://tlg.builera.app/docs/agent-playbooks/send-safely
verified: 2026-10-24
app_version: "2.0"
---

# 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.


## 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`](https://tlg.builera.app/docs/reference/rest/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.

> [!IMPORTANT]
> Điểm dừng — hỏi người
>
> Nếu người nhận, nội dung hoặc tài khoản chưa được cho phép, dừng trước bước gửi. Không dùng một lần “gửi thử” tới khách để kiểm tra kết nối.

6. Gọi MCP `messages_send`, hoặc REST operation `messages.send`.
7. Lưu ID thao tác trả về.
8. Gọi `operations_get` để theo dõi.
9. 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:

```text
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](https://tlg.builera.app/docs/agent-playbooks/investigate-failed-job) và [hạn mức Telegram](https://tlg.builera.app/docs/safety/telegram-limits).