# API Broadcast
Một **broadcast** (bản tin) là một lần gửi đi: bao gồm đối tượng nhận, tin nhắn mở đầu, một kênh và lịch trình. Tùy chọn, nó cũng chỉ định AI Agent xử lý các phản hồi nhận được. Broadcasts API cho phép bạn xây dựng, định giá, khởi chạy và giám sát các lần gửi đó từ mã nguồn của riêng bạn thay vì từ bảng điều khiển. Để biết thông tin về chính sản phẩm này, hãy xem [hướng dẫn về Broadcasts](../broadcasts/broadcasts.md).
- **URL cơ sở** — `https://api.youraiconnector.com/v1`
- **Xác thực** — khóa API của bạn (xem [Xác thực](authentication.md))
- **Lỗi & phân trang** — xem [Lỗi & Phân trang](errors-and-pagination.md)
Tất cả các ví dụ dưới đây đều hiển thị dạng truy vấn `?apiKey=` trong cURL và tiêu đề `X-API-Key` trong JavaScript và Python — cả hai đều hoạt động trên mọi endpoint.
> **Trong trình khám phá API.** Mọi endpoint trên trang này đều nằm trong đặc tả OpenAPI đã xuất bản, vì vậy bạn có thể duyệt qua các trường chính xác của nó và chạy các yêu cầu trực tiếp trong [trình khám phá API](reference.md).
---
## Cách tạo một lần gửi
Việc gửi một broadcast bao gồm bốn lệnh gọi, không phải một:
1. **Tạo** broadcast với đối tượng nhận, kênh và lịch trình — nó bắt đầu ở trạng thái `Draft`.
2. **Thiết lập tin nhắn mở đầu.** Trên WhatsApp Business, điều đó có nghĩa là gửi một mẫu tin nhắn để phê duyệt (hoặc chọn một mẫu bạn đã được phê duyệt). Trên mọi kênh khác, đó là văn bản thuần túy.
3. **Ước tính chi phí** nếu bạn muốn kiểm tra giá trước khi chi tiêu bất cứ thứ gì (tùy chọn).
4. **Khởi chạy.** Việc khởi chạy sẽ thực hiện kiểm tra toàn diện — đối tượng, tin nhắn, phê duyệt mẫu, người gửi được kết nối — và bắt đầu gửi hoặc cho bạn biết chính xác những gì còn thiếu.
Không có gì được gửi đi cho đến khi bạn gọi lệnh khởi chạy.
---
## Đối tượng broadcast
```json
{
"id": "bcd123abc456",
"name": "June promo",
"status": "Draft",
"channel": "whatsapp",
"agent_id": "agt_789",
"list_id": "lst_456",
"list_name": "Newsletter subscribers",
"total_contacts": 240,
"send_to_new_list_members": false,
"whats_app_template": {
"body": "Hi {{first_name}}, our June offer is live.",
"status": "approved",
"sid": "HX0123...",
"language": "en",
"category": "marketing",
"variables": ["first_name"]
},
"execution_date": 1781000000000,
"drip_mode": true,
"time_critical": false,
"total_contacts_sent": 0,
"credits_used": 0,
"created_at": 1780900000000,
"last_modified_at": 1780900000000
}
```
**Dấu thời gian (timestamp) được trả về dưới dạng mili giây epoch** (`execution_date`, `created_at`, `last_modified_at`, …), và bất kỳ tham chiếu liên hệ nào cũng được trả về dưới dạng chuỗi đường dẫn như `contacts/uid_whatsapp_15551234567`.
### Các trường bạn thiết lập
| Trường | Mô tả |
|---|---|
| `name` | Tên của broadcast trong bảng điều khiển. |
| `channel` | Kênh duy nhất mà broadcast này gửi đi: `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `messenger`, `facebook`, `telegram`, `instagram_private`, `line`, `viber`, `imessage`, `email`, `chat_widget`, `custom_channel`. Một broadcast chỉ có chính xác một kênh — để gửi cùng nội dung đó ở nơi khác, hãy [sao chép nó sang kênh khác](#duplicate-a-broadcast). `tiktok` và `skool` chỉ dành cho phản hồi và không bao giờ có thể được sử dụng để phát tin. |
| `agent_id` | AI Agent trả lời các phản hồi. Để trống `null` thì các phản hồi sẽ chuyển vào hộp thư đến của nhóm bạn. |
| `list_id` | Danh sách liên hệ để gửi đến. Đây là cách bạn thiết lập đối tượng nhận từ API — xem [Danh bạ](contacts.md) để tạo và điền danh sách. |
| `list_name` | Tên hiển thị bên cạnh broadcast. Chỉ mang tính thẩm mỹ. |
| `send_to_new_list_members` | `true` giữ cho broadcast luôn hoạt động để bất kỳ ai được thêm vào danh sách sau đó cũng nhận được tin nhắn mở đầu. |
| `whats_app_template` | Tin nhắn mở đầu. Trên WhatsApp Business, đây là một mẫu đã được phê duyệt thực tế; trên mọi kênh khác, `body` của nó được sử dụng làm văn bản mở đầu thuần túy. Thiết lập nó thông qua [các endpoint mẫu](#the-opening-message), không phải làm thủ công. |
| `opener_media` | Một hình ảnh hoặc video được gửi kèm với tin nhắn mở đầu. Luôn gửi toàn bộ đối tượng (hoặc `null` để xóa nó) — việc ghi các khóa riêng lẻ bên trong nó sẽ bị từ chối. Không được hỗ trợ trên SMS. |
| `execution_date` | Thời điểm gửi. Gửi dấu thời gian ISO 8601 hoặc mili giây epoch. Một ngày trong tương lai sẽ lên lịch gửi; bỏ qua nó (hoặc sử dụng ngày trong quá khứ) để gửi ngay khi bạn khởi chạy. |
| `drip_mode` | `true` điều tiết việc gửi theo từng đợt theo thời gian thay vì gửi tất cả cùng một lúc. |
| `time_critical` | `true` chọn không tham gia điều tiết tự động vốn được kích hoạt khi có trên 50 liên hệ — dành cho đối tượng nhận đã quen thuộc và cần nhận tin nhắn ngay lập tức. Nó không nâng giới hạn gửi hàng ngày của kênh. |
| `batch_size` | Số lượng liên hệ mỗi đợt khi gửi nhỏ giọt (drip). |
| `follow_up_config` | Chuỗi theo dõi cho những liên hệ không bao giờ phản hồi. |
Bất cứ thứ gì bạn gửi dưới dạng `user_id`, `id`, `status` hoặc `source_campaign_id` đều bị bỏ qua khi tạo và bị loại bỏ khi cập nhật — trạng thái chỉ thay đổi thông qua các endpoint khởi chạy, tạm dừng và tiếp tục bên dưới.
### Các trường do nền tảng duy trì
`status`, `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate`, `credits_used`, `paused_reason`, `completion_summary`, các bộ đếm đợt, và `contacts` (các liên hệ riêng lẻ được đính kèm từ bảng điều khiển, đọc lại dưới dạng chuỗi đường dẫn). Chỉ đọc, không ghi vào các trường này.
### Trạng thái
| Trạng thái | Ý nghĩa |
|---|---|
| `Draft` | Đang được xây dựng. Không có gì được lên lịch. |
| `Pending Approval` | Đã khởi chạy, nhưng mẫu WhatsApp của nó vẫn đang chờ quyết định. Nó sẽ tự động bắt đầu gửi sau khi mẫu được phê duyệt — bạn không cần phải khởi chạy lại. |
| `Scheduled` | Đã khởi chạy với `execution_date` trong tương lai. |
| `Sending` | Đang gửi (một chương trình phát sóng được thiết lập cho các thành viên danh sách mới sẽ ở trạng thái này trong khi chờ đợi họ). |
| `Paused` | Đã tạm dừng — bởi bạn hoặc tự động bởi kiểm tra an toàn. |
| `Sent` | Đã hoàn tất. |
| `Failed` | Đã hoàn tất với hơn một nửa số lần gửi bị lỗi. |
---
## Tạo chương trình phát sóng
`POST /broadcasts` — tạo một `Draft`.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "June promo",
"channel": "whatsapp",
"list_id": "lst_456",
"agent_id": "agt_789",
"drip_mode": true,
"execution_date": "2026-06-15T09:00:00.000Z"
}'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
method: "POST",
headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
name: "June promo",
channel: "whatsapp",
list_id: "lst_456",
agent_id: "agt_789",
drip_mode: true,
execution_date: "2026-06-15T09:00:00.000Z",
}),
});
const { broadcast_id } = await res.json();
```
**Python**
```python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/broadcasts",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"name": "June promo",
"channel": "whatsapp",
"list_id": "lst_456",
"agent_id": "agt_789",
"drip_mode": True,
"execution_date": "2026-06-15T09:00:00.000Z",
},
)
print(res.json()["broadcast_id"])
```
**Phản hồi** (`201`)
```json
{ "success": true, "broadcast_id": "bcd123abc456" }
```
---
## Liệt kê các chương trình phát sóng
`GET /broadcasts` — mọi chương trình phát sóng trên tài khoản, hiển thị cái mới nhất trước. |
**Các tham số truy vấn**
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
| `status` | Không | Chỉ trả về các chương trình phát sóng ở một trạng thái, ví dụ: `Sending`. Hãy khớp chính xác cách viết trong [bảng trạng thái](#statuses). |
```bash
curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"
```
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();
```
```python
res = requests.get(
"https://api.youraiconnector.com/v1/broadcasts",
headers={"X-API-Key": "YOUR_API_KEY"},
params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]
```
**Phản hồi** (`200`)
```json
{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }
```
---
## Lấy thông tin chương trình phát sóng
`GET /broadcasts/{broadcastId}` — trả về `{ "success": true, "broadcast": { ... } }`. Sử dụng nó để thăm dò một lần gửi đang chạy: `total_contacts_sent`, `unique_contacts_replied`, `overall_reply_rate` và `credits_used` sẽ cập nhật khi quá trình diễn ra. |
```bash
curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"
```
Một chương trình phát sóng không tồn tại trên tài khoản của bạn sẽ trả về `404`.
---
## Cập nhật chương trình phát sóng
`PUT /broadcasts/{broadcastId}` — chỉ gửi các trường bạn muốn thay đổi. Bạn cũng có thể giải quyết một khóa đơn lẻ bên trong một đối tượng lồng nhau bằng đường dẫn dấu chấm, ví dụ: `"whats_app_template.body"`.
```bash
curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'
```
```javascript
await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
method: "PUT",
headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});
```
Một nội dung trống sẽ trả về `400`. Hai quy tắc cần biết:
- **`opener_media` là tất cả hoặc không có gì.** Gửi toàn bộ đối tượng hoặc `null` để xóa tệp đính kèm. Đường dẫn dấu chấm vào nó (`opener_media.name`) sẽ bị từ chối với `400`, vì tệp đính kèm được cập nhật một nửa sẽ mô tả một tệp không tồn tại.
- **Trạng thái không thể chỉnh sửa.** Sử dụng [khởi chạy](#launch-a-broadcast), [tạm dừng](#pause-and-resume) và [tiếp tục](#pause-and-resume).
---
## Tin nhắn mở đầu
Mỗi chương trình phát sóng đều mang phần mở đầu của nó trong `whats_app_template`. Ý nghĩa của điều đó phụ thuộc vào kênh:
- **WhatsApp Business** — đó phải là một mẫu đã được WhatsApp phê duyệt. Sử dụng một trong hai điểm cuối bên dưới.
- **Mọi kênh khác** (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — `body` của cùng trường đó chỉ đơn giản là văn bản được gửi đi. Việc gửi nó qua điểm cuối bên dưới sẽ lưu trữ và đánh dấu nó là sẵn sàng mà không cần thông qua WhatsApp.
### Gửi mẫu để phê duyệt
`POST /broadcasts/{broadcastId}/template`
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| `body` | Có | Văn bản tin nhắn, tối đa 1024 ký tự. Sử dụng các trình giữ chỗ `{{variable}}` để cá nhân hóa. |
| `name` | Không | Tên mẫu. Mặc định là tên của chương trình phát sóng. |
| `language` | Không | Mã ngôn ngữ. Mặc định là `en`. |
| `category` | Không | `marketing` (mặc định), `utility`, `authentication`, hoặc `authentication-international`. Đây là mức giá cho lượt gửi, vì vậy hãy giữ tính trung thực. |
| `variables` | Không | Tên các trình giữ chỗ, theo thứ tự xuất hiện. Hãy bỏ qua nó và chúng sẽ được đọc từ phần nội dung — đây thường là điều bạn muốn, vì lượt gửi sẽ điền chúng từ mỗi liên hệ. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"body": "Hi {{first_name}}, our June offer is live until Friday.",
"language": "en",
"category": "marketing"
}'
```
**Phản hồi** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }
```
`template_status` là những gì WhatsApp thông báo: `pending` trong khi đang được xem xét, `approved` khi có thể sử dụng, `rejected` nếu bị từ chối. Trên kênh không phải WhatsApp, nó sẽ trả về ngay lập tức là `approved` với `template_sid: null` — không có gì cần xem xét.
Những điều sẽ ngăn cản bạn:
- Gửi trong khi một mẫu trước đó vẫn đang được xem xét sẽ trả về `400`. Hãy đợi quyết định trước.
- Việc chỉnh sửa một mẫu hiện đã được phê duyệt sẽ giữ cho mẫu đã phê duyệt hoạt động cho đến khi mẫu mới được trả về, vì vậy một chương trình phát sóng đang chạy sẽ không bao giờ mất phần mở đầu.
- Trên số WhatsApp được kết nối trực tiếp qua Meta, một chương trình phát sóng có đính kèm hình ảnh hoặc video không thể được gửi (`400`) — các tệp đính kèm được hỗ trợ trên kênh WhatsApp Business được quản lý và trên WhatsApp Web.
### Sử dụng mẫu bạn đã được phê duyệt
`POST /broadcasts/{broadcastId}/template/select` — sao chép một mẫu đã được phê duyệt từ [thư viện mẫu](templates.md) của bạn vào chương trình phát sóng, vì vậy không cần phải chờ đợi.
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| `template_id` | Có | ID của một mẫu đã được phê duyệt trên tài khoản của bạn. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "template_id": "tpl_abc123" }'
```
**Phản hồi** (`200`)
```json
{
"success": true,
"broadcast_id": "bcd123abc456",
"template_status": "approved",
"template_sid": "HX0123...",
"body": "Hi {{first_name}}, our June offer is live until Friday.",
"name": "june_promo",
"language": "en",
"variables": ["first_name"],
"category": "marketing"
}
```
Việc phê duyệt được xác minh từ phía chúng tôi dựa trên hồ sơ thư viện — bạn chỉ cần gửi ID. Bạn sẽ nhận được `400` nếu chương trình phát sóng không phải là bản nháp WhatsApp, nếu mẫu không được phê duyệt, nếu đó là mẫu tiếp theo thay vì mẫu mở đầu, hoặc nếu chương trình phát sóng có tệp đính kèm (các mẫu trong thư viện chỉ chứa văn bản). ID mẫu không có trên tài khoản của bạn sẽ trả về `404`.
---
## Ước tính chi phí
`POST /broadcasts/{broadcastId}/estimate-cost` — định giá lượt gửi trước khi bạn cam kết thực hiện. Có sẵn trên các chương trình phát sóng `whatsapp` và `sms`; bất kỳ kênh nào khác sẽ trả về `400`. Chương trình phát sóng cần có `list_id`, vì ước tính dựa trên số lượng đối tượng.
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"
```
**Phản hồi từ WhatsApp** (`200`) — tín dụng, được phân loại theo quốc gia đích:
```json
{
"success": true,
"channel": "whatsapp",
"billing_mode": "credits",
"data": {
"countries": [
{ "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
{ "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
],
"totalContacts": 240,
"totalTemplateCost": 270,
"templateCategory": "marketing",
"billing_mode": "credits",
"service_messages_billable_soon": false
}
}
```
**Phản hồi SMS** (`200`) — Đô la Mỹ, dựa trên giá Twilio trực tiếp cho tài khoản Twilio của riêng bạn:
```json
{
"success": true,
"channel": "sms",
"billing_mode": "twilio_direct",
"data": {
"totalContacts": 240,
"messageLength": 118,
"segmentsPerMessage": 1,
"totalSegments": 240,
"estimatedCostUsd": 1.788,
"priceUnit": "USD",
"billedByTwilio": true,
"billing_mode": "twilio_direct",
"service_messages_billable_soon": false
}
}
```
**Đọc `billing_mode` trước khi bạn hiển thị một số.** Nó cho bạn biết ai là người bị tính phí:
| `billing_mode` | Ai thanh toán | Ý nghĩa của các con số |
|---|---|---|
| `credits` | Tài khoản Your AI Connector của bạn | `totalTemplateCost` và các con số theo quốc gia là số tín dụng. |
| `twilio_direct` | Tài khoản Twilio của riêng bạn | `estimatedCostUsd` là số tiền Twilio sẽ tính phí bạn. |
| `meta_waba_direct` | Tài khoản WhatsApp Business của riêng bạn, do Meta tính phí | Mọi con số tín dụng đều quay lại `null` — một cách cố ý, để không bao giờ bị nhầm lẫn là "miễn phí". Số lượng quốc gia và liên hệ vẫn chính xác. |
SMS không có thông tin xác thực Twilio được kết nối vẫn trả về số lượng phân đoạn, với `estimatedCostUsd: 0` — không có giá nào để tra cứu.
---
## Khởi chạy chương trình phát sóng
`POST /broadcasts/{broadcastId}/launch`
Việc khởi chạy sẽ kiểm tra mọi thứ trước rồi mới tiến hành phát sóng. Không có việc khởi chạy một phần: hoặc là nó bắt đầu, hoặc là không có gì thay đổi và bạn nhận được thông báo lỗi giải thích lý do tại sao.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
method: "POST",
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())
```
**Phản hồi** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }
```
`status` là nơi chương trình phát sóng đã hạ cánh:
- `Scheduled` — `execution_date` đang ở trong tương lai.
- `Sending` — nó đã bắt đầu ngay bây giờ.
- `Pending Approval` — mẫu WhatsApp vẫn đang được xem xét. Nó sẽ tự gửi ngay khi mẫu được phê duyệt; đừng gọi lại lệnh khởi chạy.
Chỉ có thể khởi chạy `Draft` (hoặc chương trình phát sóng `Pending Approval` có mẫu đã được phê duyệt kể từ đó) — bất kỳ thứ gì khác sẽ trả về `400`.
### Tại sao lệnh khởi chạy bị từ chối
Mỗi trường hợp này đều trả về `400` kèm theo thông báo `error` bằng ngôn ngữ đơn giản:
| Vấn đề | Cần khắc phục điều gì |
|---|---|
| Không có đối tượng | Thiết lập `list_id` (hoặc đính kèm danh bạ) trước khi khởi chạy. |
| Không có tin nhắn mở đầu | Thiết lập phần mở đầu — xem [Tin nhắn mở đầu](#the-opening-message). |
| Tệp đính kèm trên SMS | SMS không thể chứa hình ảnh hoặc video. Hãy xóa tệp đính kèm hoặc chuyển chương trình phát sóng sang WhatsApp. |
| Tệp đính kèm không khớp với mẫu đã được phê duyệt | Trên WhatsApp, phương tiện nằm trong mẫu đã được phê duyệt, vì vậy việc thay đổi tệp đính kèm sau đó đồng nghĩa với việc phải gửi lại mẫu. |
| Mẫu bị từ chối | Viết lại tin nhắn và gửi lại lần nữa. |
| Mẫu chưa bao giờ được gửi | Hãy gửi nó (hoặc chọn một mẫu đã được phê duyệt) trước. |
| Mẫu đã được phê duyệt nhưng thiếu trong tài khoản WhatsApp của bạn | Thường là do mẫu được phê duyệt trước khi số điện thoại kết nối xong. Hãy gửi lại lần nữa. |
| Không có người gửi được kết nối cho kênh | Kết nối kênh trước — xem [Các kênh](channels.md). |
| Kênh chỉ nhận phản hồi | TikTok và Skool không cho phép doanh nghiệp bắt đầu cuộc trò chuyện, vì vậy không thể phát sóng trên các kênh này. |
| Đã được thiết lập | Chương trình phát sóng đã có lịch gửi. Hãy tạm dừng nó trước khi khởi chạy lại. |
| Vẫn đang chờ phê duyệt | Nó sẽ tự gửi khi mẫu được phê duyệt. |
| Tài khoản WhatsApp Business bị Meta chặn | Meta đã dừng các cuộc trò chuyện do doanh nghiệp khởi xướng trên Tài khoản WhatsApp Business của bạn — thường là do vấn đề về phương thức thanh toán. Hãy khắc phục trong Meta Business Manager. |
| Bắt đầu từ chiến dịch cổ điển | Hãy khởi chạy nó từ trình chỉnh sửa chiến dịch. Xem [các chiến dịch cổ điển trong Broadcasts](#broadcasts-that-mirror-a-classic-campaign). |
---
## Tạm dừng và tiếp tục
`POST /broadcasts/{broadcastId}/pause` dừng chương trình phát sóng `Sending` hoặc `Scheduled` và hủy bỏ mọi thứ đang chờ xử lý.
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"
```
Tạm dừng một chương trình phát sóng `Pending Approval` sẽ đưa nó trở lại trạng thái `Draft` — chưa có gì được lên lịch, vì vậy không có gì để tiếp tục. Bất kỳ trạng thái nào khác đều trả về `400`.
`POST /broadcasts/{broadcastId}/resume` khởi động lại một chương trình phát sóng `Paused`:
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"
```
**Phản hồi** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456" }
```
Nó tiếp tục ở trạng thái `Sending`, hoặc quay lại trạng thái `Scheduled` nếu `execution_date` của nó vẫn còn trong tương lai. Chỉ chương trình phát sóng `Paused` mới có thể được tiếp tục.
---
## Tiếp tục gửi sau khi tạm dừng do tương tác thấp
`POST /broadcasts/{broadcastId}/override-engagement-guard`
Trong khi chương trình phát sóng gửi theo từng đợt, chúng tôi đo lường số lượng người đã trả lời mỗi đợt trước khi bắt đầu đợt tiếp theo. Nếu hầu như không có ai trả lời, chương trình phát sóng sẽ tự động tạm dừng — việc tiếp tục gửi vào khoảng lặng là cách nhanh nhất để khiến một số điện thoại bị lọc hoặc chặn. Đó chính là nút **Tiếp tục dù sao đi nữa** (Continue anyway) trong bảng điều khiển.
Vì tỷ lệ trả lời gây ra việc tạm dừng không thể thay đổi khi chương trình phát sóng đã dừng, một lệnh [tiếp tục](#pause-and-resume) thông thường sẽ chỉ bị tạm dừng lại bởi lần kiểm tra tiếp theo. Điểm cuối này là quyết định để tiếp tục bất chấp: nó ghi lại sự ghi đè trên chương trình phát sóng đó và dỡ bỏ lệnh tạm dừng trong cùng một lệnh gọi nếu chương trình phát sóng bị tạm dừng do tương tác thấp.
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"
```
**Phản hồi** (`200`)
```json
{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }
```
- `resumed: true` — chương trình phát sóng đã bị tạm dừng do tương tác thấp và hiện đang chạy lại; `status` là nơi nó tiếp tục.
- `resumed: false` — không có gì được dỡ bỏ, sự ghi đè chỉ đơn giản được ghi lại cho các lần kiểm tra trong tương lai. Đó là những gì bạn nhận được nếu chương trình phát sóng chưa bao giờ bị tạm dừng, hoặc bị tạm dừng vì lý do khác (bạn đã tự tay tạm dừng, đạt đến giới hạn gửi hoặc quá nhiều lần gửi bị lỗi). Những lệnh tạm dừng đó không được dỡ bỏ tại đây — hãy tự tiếp tục sau khi bạn đã xử lý nguyên nhân.
Sự ghi đè chỉ áp dụng cho chương trình phát sóng này. Đây không phải là cài đặt tài khoản và việc gọi lệnh này hai lần là an toàn.
---
## Sao chép chương trình phát sóng
`POST /broadcasts/{broadcastId}/duplicate` — sao chép đối tượng, tin nhắn và cài đặt vào một `Draft` mới. Mọi thứ về lần chạy trước (bộ đếm, đợt gửi, lịch trình, thống kê trả lời) đều bắt đầu mới.
| Trường | Bắt buộc | Mô tả |
|---|---|---|
| `to_channel` | Không | Tạo bản sao trên một kênh khác. Đây là cách bạn gửi cùng một nội dung trên hai kênh — một chương trình phát sóng chỉ có một kênh duy nhất. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "to_channel": "sms" }'
```
**Phản hồi** (`201`)
```json
{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }
```
Bản sao không bao giờ kế thừa sự phê duyệt WhatsApp trực tiếp: trên bản sao WhatsApp, mẫu tin nhắn sẽ cần bạn xác nhận, và trên bản sao sang kênh khác, nó sẽ bị loại bỏ và văn bản trở thành phần mở đầu thuần túy. Việc sao chép sang SMS cũng loại bỏ mọi tệp đính kèm, vì SMS không thể gửi tệp đính kèm.
---
## Xóa chương trình phát sóng
`DELETE /broadcasts/{broadcastId}`
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"
```
Một `Sending` hoặc `Scheduled` broadcast bị từ chối với `400` — hãy tạm dừng nó trước.
---
## Các broadcast phản chiếu một chiến dịch cổ điển
Các chiến dịch cổ điển gửi tin nhắn cũng xuất hiện trong Broadcasts, và API trả về chúng cùng với các broadcast gốc (chúng mang một `source_campaign_id`). Chúng hoạt động hơi khác một chút vì chiến dịch vẫn là thành phần quản lý chính:
- **Chỉnh sửa** đối tượng, tin nhắn hoặc lịch trình đều hoạt động và được ghi lại vào chiến dịch.
- **Kênh, tác nhân trả lời, tệp đính kèm và tất cả bộ đếm lượt chạy là chỉ đọc** ở đây — `400` nếu bạn cố gắng thay đổi chúng. Hãy thay đổi chúng trên chiến dịch.
- **Khởi chạy** trả về `400` hướng bạn đến trình chỉnh sửa chiến dịch.
- **Tạm dừng và tiếp tục** hoạt động và tác động lên chiến dịch.
- **Xóa** trả về `400` — hãy xóa chiến dịch thay thế, và mục Broadcasts của nó cũng sẽ bị xóa theo.
- **Sao chép** tạo ra một broadcast gốc độc lập, đây là cách được hỗ trợ để chuyển một chiến dịch đã được kiểm chứng sang.
---
## Lỗi
Các yêu cầu thất bại trả về `{"success": false, "error": ""}` với các trạng thái sau:
| Trạng thái | Ý nghĩa |
|---|---|
| `400` | Có điều gì đó không ổn về yêu cầu hoặc trạng thái của broadcast — thiếu trường, tệp đính kèm không hợp lệ, hoặc hành động khởi chạy/tạm dừng/tiếp tục/xóa không được phép trong trạng thái hiện tại của broadcast. Thông báo `error` sẽ nêu rõ lý do. |
| `401` | Thiếu hoặc khóa API không hợp lệ. |
| `403` | Gói của bạn không bao gồm quyền truy cập API. |
| `404` | Không có broadcast như vậy trong tài khoản của bạn (hoặc, khi chọn mẫu, không có mẫu như vậy). |
| `429` | Giới hạn tốc độ. Hãy dừng lại và thử lại sau. |
| `500` | Đã xảy ra lỗi ở phía chúng tôi. Hãy thử lại sau một thời gian ngắn. |
---
## Các bước tiếp theo
- [Hướng dẫn về Broadcasts](../broadcasts/broadcasts.md) — sản phẩm đằng sau các điểm cuối này, bao gồm tốc độ gửi và hành vi an toàn
- [API Danh bạ](contacts.md) — xây dựng danh sách mà broadcast gửi đến
- [API Mẫu](templates.md) — quản lý các mẫu WhatsApp đã được phê duyệt mà bạn có thể chọn
- [API Webhooks](webhooks.md) — đăng ký `Broadcast Started` và `Broadcast Completed` thay vì thăm dò