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.

• URL cơ sở — https://api.youraiconnector.com/v1
• Xác thực — khóa API của bạn (xem Xác thực)
• Lỗi & phân trang — xem Lỗi & Phân trang

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.

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 #

{
  "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 #

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 #

Tạo chương trình phát sóng #

POST /broadcasts — tạo một Draft.

cURL

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

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

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)

{ "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

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

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)

{ "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. |

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

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" }'

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, tạm dừng và tiếp tục.

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

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)

{ "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 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.

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)

{
  "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.

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:

{
  "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:

{
  "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í:

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

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

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

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)

{ "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:

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

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:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Phản hồi (200)

{ "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 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.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Phản hồi (200)

{ "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.

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)

{ "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}

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": "<message>"} với các trạng thái sau:

Các bước tiếp theo #

• Hướng dẫn về Broadcasts — 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ạ — xây dựng danh sách mà broadcast gửi đến
• API Mẫu — quản lý các mẫu WhatsApp đã được phê duyệt mà bạn có thể chọn
• API Webhooks — đăng ký Broadcast Started và Broadcast Completed thay vì thăm dò