广播 API

广播是一次外发消息：包含受众、开场白、一个渠道和一个时间表。它还可以选择性地指定处理回复的 AI 代理。广播 API 允许您直接从自己的代码中构建、定价、启动和监控这些发送任务，而无需使用仪表板。有关产品本身的信息，请参阅广播指南。

基础 URL — https://api.youraiconnector.com/v1
身份验证 — 您的 API 密钥（请参阅身份验证）
错误与分页 — 请参阅错误与分页

以下所有示例均展示了 cURL 中的 ?apiKey= 查询形式，以及 JavaScript 和 Python 中的 X-API-Key 标头——两者均适用于所有端点。

在 API 探索器中。 本页面上的每个端点都包含在已发布的 OpenAPI 规范中，因此您可以在 API 探索器中浏览其确切字段并运行实时请求。

如何组合发送任务

发送广播需要四个调用，而不是一个：

创建广播及其受众、渠道和时间表 — 它最初的状态为 Draft。
设置开场白。 在 WhatsApp Business 上，这意味着提交模板以供批准（或选择您已批准的模板）。在所有其他渠道上，它就是纯文本。
估算成本（可选），如果您想在花费任何费用之前检查价格。
启动它。 启动会运行全面检查 — 受众、消息、模板批准、已连接的发送者 — 并开始发送或准确告知您缺少什么。

在您调用启动之前，不会发送任何内容。

广播对象

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

时间戳以 epoch 毫秒数返回（execution_date、created_at、last_modified_at 等），任何联系人引用都以路径字符串的形式返回，例如 contacts/uid_whatsapp_15551234567。

您设置的字段

字段	描述
`name`	广播在仪表板中的名称。
`channel`	此广播发送所使用的唯一渠道：`whatsapp`、`whatsapp_web`、`sms`、`instagram`、`messenger`、`facebook`、`telegram`、`instagram_private`、`line`、`viber`、`imessage`、`email`、`chat_widget`、`custom_channel`。一个广播只能有一个渠道 — 要在其他地方发送相同内容，请将其复制到另一个渠道。`tiktok` 和 `skool` 仅用于回复，不能用于广播。
`agent_id`	回答回复的 AI 代理。留空 `null`，回复将进入您的团队收件箱。
`list_id`	要发送到的联系人列表。这是您通过 API 设置受众的方式 — 请参阅联系人以了解如何创建和填充列表。
`list_name`	显示在广播旁边的显示名称。仅用于装饰。
`send_to_new_list_members`	`true` 保持广播处于激活状态，以便稍后添加到列表中的任何人也能收到开场白。
`whats_app_template`	开场白。在 WhatsApp Business 上，它是一个真实的已批准模板；在所有其他渠道上，其 `body` 用作纯文本开场白。请通过模板端点设置它，而不是手动设置。
`opener_media`	随开场白发送的一张图片或视频。始终发送整个对象（或 `null` 以将其删除） — 在其中写入单个键将被拒绝。短信不支持此功能。
`execution_date`	发送时间。发送 ISO 8601 时间戳或 epoch 毫秒数。未来的日期会安排发送；省略它（或使用过去的日期）以在您启动时立即发送。
`drip_mode`	`true` 会随时间分批发送，而不是一次性发送。
`time_critical`	`true` 选择不使用超过 50 个联系人时自动触发的自动分批 — 适用于需要立即接收消息的活跃受众。它不会提高渠道本身的每日发送限制。
`batch_size`	分批发送时每批的联系人数量。
`follow_up_config`	针对从未回复的联系人的后续跟进链。

您作为 user_id、id、status 或 source_campaign_id 发送的任何内容在创建时都会被忽略，在更新时会被丢弃 — 状态只能通过下方的启动、暂停和恢复端点进行更改。

平台维护的字段

status、total_contacts_sent、unique_contacts_replied、overall_reply_rate、credits_used、paused_reason、completion_summary、批次计数器以及 contacts（从仪表板附加的单个联系人，以路径字符串形式读回）。请读取它们，不要写入它们。

状态

状态	含义
`Draft`	正在构建中。尚未安排发送。
`Pending Approval`	已启动，但其 WhatsApp 模板仍在等待审核。模板获批后，它会自动开始发送——您无需再次启动。
`Scheduled`	已启动，但设置了未来的 `execution_date`。
`Sending`	正在积极发送（为新列表成员准备的广播在等待他们加入时会保持此状态）。
`Paused`	已暂停——由您手动暂停，或因安全检查自动暂停。
`Sent`	已完成。
`Failed`	已完成，但超过一半的发送失败。

创建广播

POST /broadcasts — 创建一个 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"])

响应 (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

列出广播

GET /broadcasts — 账户上的所有广播，按最新排序。

查询参数

参数	必需	描述
`status`	否	仅返回处于特定状态的广播，例如 `Sending`。请确保拼写与状态表中的完全一致。

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

响应 (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

获取广播

GET /broadcasts/{broadcastId} — 返回 { "success": true, "broadcast": { ... } }。使用它来轮询正在进行的发送任务：total_contacts_sent、unique_contacts_replied、overall_reply_rate 和 credits_used 会随进度更新。

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

如果广播在您的账户中不存在，则返回 404。

更新广播

PUT /broadcasts/{broadcastId} — 仅发送您想要更改的字段。您也可以使用点号路径寻址嵌套对象中的单个键，例如 "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" }),
});

空请求体返回 400。有两条规则需要注意：

opener_media 是全有或全无的。 发送完整的对象，或发送 null 以删除附件。指向其中的点号路径（opener_media.name）会被拒绝并返回 400，因为部分更新的附件会指向一个不存在的文件。
状态不可编辑。 请使用启动、暂停和恢复功能。

开场消息

每条广播都在 whats_app_template 中携带其开场白。其具体含义取决于渠道：

WhatsApp Business — 必须是 WhatsApp 已批准的模板。请使用以下两个端点之一。
所有其他渠道（WhatsApp Web、SMS、Instagram、Messenger、Telegram 等）— 同一字段的 body 仅仅是发送的文本。通过以下端点提交它会将其存储并标记为就绪，完全无需 WhatsApp 介入。

提交模板以供审批

POST /broadcasts/{broadcastId}/template

字段	必填	描述
`body`	是	消息文本，最多 1024 个字符。使用 `{{variable}}` 占位符进行个性化设置。
`name`	否	模板名称。默认为广播名称。
`language`	否	语言代码。默认为 `en`。
`category`	否	`marketing`（默认）、`utility`、`authentication` 或 `authentication-international`。这是发送的定价依据，请务必如实填写。
`variables`	否	占位符名称，按其出现的顺序排列。如果省略，它们将从正文中读取——这通常是您所需要的，因为发送时会根据每个联系人填充它们。

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

响应 (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status 是 WhatsApp 的反馈：审核中为 pending，可用时为 approved，被拒绝时为 rejected。在非 WhatsApp 渠道上，它会直接返回 approved 和 template_sid: null ——无需审核。

会阻止您操作的情况：

在前一个模板仍在审核中时提交会返回 400。请先等待审核结果。
编辑当前已批准的模板时，已批准的版本会保持在线，直到新模板返回，因此正在进行的广播永远不会失去其开场白。
在通过 Meta 直接连接的 WhatsApp 号码上，无法提交带有图片或视频附件的广播（400）——附件仅在托管的 WhatsApp Business 通道和 WhatsApp Web 上受支持。

使用您已获批的模板

POST /broadcasts/{broadcastId}/template/select — 将已批准的模板从您的模板库复制到广播中，因此无需等待。

字段	必填	描述
`template_id`	是	您账户中已批准模板的 ID。

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

响应 (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"
}

审批结果由我们根据库记录进行验证——您只需发送 ID。如果广播不是 WhatsApp 草稿、模板未获批准、模板是后续模板而非开场白，或者广播带有附件（库模板仅限文本），您将收到 400。如果模板 ID 不在您的账户中，则返回 404。

估算成本

POST /broadcasts/{broadcastId}/estimate-cost — 在您提交发送前对发送进行定价。适用于 whatsapp 和 sms 广播；任何其他渠道均返回 400。广播需要 list_id，因为估算会统计受众人数。

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

WhatsApp 响应 (200) — 按目标国家/地区细分的额度：

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

短信回复 (200) — 美元，基于您自己的 Twilio 账户的实时 Twilio 定价：

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

在显示号码之前请阅读 billing_mode。 它会告诉您谁将被收费：

`billing_mode`	谁来支付	数字的含义
`credits`	您的 Your AI Connector 账户	`totalTemplateCost` 以及各国家的数字均为点数。
`twilio_direct`	您自己的 Twilio 账户	`estimatedCostUsd` 是 Twilio 将向您收取的费用。
`meta_waba_direct`	您自己的 WhatsApp Business 账户，由 Meta 收费	每个点数数字都会返回 `null` —— 这是刻意为之，以防被误认为是“免费”。国家和联系人计数仍然准确。

未连接 Twilio 凭据的短信仍然会返回分段计数，并显示 estimatedCostUsd: 0 —— 因为没有可供查询的定价。

发起广播

POST /broadcasts/{broadcastId}/launch

发起操作会先检查所有内容，然后才会推进广播。不存在部分发起的情况：要么开始，要么什么都不会改变，并且您会收到一条说明原因的错误消息。

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())

响应 (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status 是广播落地的地方：

Scheduled — execution_date 在未来。
Sending — 它现在已经开始。
Pending Approval — WhatsApp 模板仍在审核中。一旦模板获得批准，它会自动发送；请勿再次调用发起。

只有 Draft（或模板此后已获批准的 Pending Approval 广播）才能被发起 —— 其他任何情况都会返回 400。

为什么发起会被拒绝

每一个此类情况都会以 400 形式返回，并附带一条通俗易懂的 error 消息：

问题	修复方法
无受众	在发起前设置 `list_id`（或添加联系人）。
无开场消息	设置开场白 —— 请参阅开场消息。
短信包含附件	短信无法携带图片或视频。请移除附件或将广播移至 WhatsApp。
附件与已批准的模板不匹配	在 WhatsApp 上，媒体内容存在于已批准的模板中，因此事后更换附件意味着需要重新提交模板。
模板被拒绝	重写消息并再次提交。
模板从未提交	请先提交（或选择一个已批准的模板）。
模板已批准但在您的 WhatsApp 账户中缺失	通常是因为模板在号码连接完成前就已批准。请再次提交。
该渠道没有已连接的发送方	请先连接渠道 —— 请参阅渠道。
仅限回复的渠道	TikTok 和 Skool 不允许企业发起对话，因此无法在这些渠道上进行广播。
已处于待发送状态	广播已经安排了发送任务。请在再次发起前将其暂停。
仍在等待批准	当模板获得批准时，它会自动发送。
WhatsApp Business 账户被 Meta 封禁	Meta 已停止您自己的 WhatsApp Business 账户发起业务对话 —— 通常是支付方式问题。请在 Meta 的商务管理平台中修复。
从经典营销活动开始	请从营销活动编辑器中发起。请参阅广播中的经典营销活动。

暂停和恢复

POST /broadcasts/{broadcastId}/pause 会停止 Sending 或 Scheduled 广播，并清除所有已排队的任务。

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

暂停 Pending Approval 广播会将其放回 Draft — 因为尚未安排任何内容，所以没有可恢复的目标。任何其他状态都会返回 400。

POST /broadcasts/{broadcastId}/resume 重启 Paused 广播：

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

响应 (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

它会恢复到 Sending，或者如果其 execution_date 仍在未来，则回到 Scheduled。只有 Paused 广播可以恢复。

在低参与度暂停后继续发送

POST /broadcasts/{broadcastId}/override-engagement-guard

当广播分批发送时，我们会衡量在开始下一批之前有多少人回复了每一批。如果几乎没有人回复，广播会自动暂停 — 在无人响应的情况下持续发送是导致号码被过滤或封禁的最快方式。这就是仪表板中的 Continue anyway（无论如何继续）按钮。

由于导致暂停的回复率在广播停止时无法改变，直接 resume（恢复）只会导致它在下一次检查时再次被暂停。此端点是决定无论如何都要继续发送：它会记录该特定广播的覆盖设置，如果广播是因为低参与度而暂停的，它会在同一次调用中解除暂停。

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

响应 (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

resumed: true — 广播因低参与度而暂停，现在已重新运行；status 是它恢复到的状态。
resumed: false — 没有解除任何暂停，该覆盖设置仅被记录以供后续检查使用。如果您从未暂停广播，或者广播因其他原因暂停（您手动暂停、达到发送限制或发送错误过多），您将得到此结果。这些暂停不会在此处解除 — 在处理完原因后，请自行恢复它。

该覆盖设置仅适用于此广播。它不是账户设置，可以安全地多次调用。

复制广播

POST /broadcasts/{broadcastId}/duplicate — 将受众、消息和设置复制到新的 Draft 中。之前运行的所有内容（计数器、批次、计划、回复统计信息）都将重新开始。

字段	必填	说明
`to_channel`	否	在不同的渠道上创建副本。这是您在两个渠道上发送相同内容的方式 — 一个广播只能有一个渠道。

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

响应 (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

副本永远不会继承现有的 WhatsApp 批准：在 WhatsApp 副本上，模板需要您的确认；而在复制到其他渠道时，模板会被丢弃，文本将变为纯文本开头。复制到短信（SMS）也会丢弃任何附件，因为短信无法发送附件。

删除广播

DELETE /broadcasts/{broadcastId}

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

Sending 或 Scheduled 广播会被 400 拒绝 — 请先暂停它。

镜像经典营销活动的广播

发送消息的经典营销活动也会出现在“广播”中，API 会将其与原生广播一并返回（它们带有 source_campaign_id）。它们的行为略有不同，因为营销活动仍然处于主导地位：

编辑受众、消息或时间表是有效的，并会同步写入到营销活动中。
渠道、回复代理、附件和所有运行计数器在此处为只读 — 如果您尝试更改它们，会收到 400。请在营销活动中更改它们。
启动会返回 400，指引您前往营销活动编辑器。
暂停和恢复功能有效，并作用于该营销活动。
删除会返回 400 — 请改为删除该营销活动，其广播条目也会随之删除。
复制会生成一个独立的、原生的广播，这是将经过验证的营销活动迁移过来的受支持方式。

错误

失败的请求会返回 {"success": false, "error": "<message>"} 以及以下状态：

状态	含义
`400`	请求或广播的状态有误 — 例如缺少字段、附件无效，或在广播当前状态下不允许进行启动/暂停/恢复/删除操作。`error` 消息会说明具体原因。
`401`	API 密钥缺失或无效。
`403`	您的套餐不包含 API 访问权限。
`404`	您的账户中不存在该广播（或在选择模板时，不存在该模板）。
`429`	速率受限。请稍后再试。
`500`	我们这边出现了问题。请稍等片刻后重试。

后续步骤

广播指南 — 这些端点背后的产品，包括节奏控制和安全行为
联系人 API — 构建广播发送的目标列表
模板 API — 管理您可以选择的已批准 WhatsApp 模板
Webhooks API — 订阅 Broadcast Started 和 Broadcast Completed，而不是进行轮询

广播 API #

如何组合发送任务 #

广播对象 #

您设置的字段 #

平台维护的字段 #

状态 #

创建广播 #

列出广播 #

获取广播 #

更新广播 #

开场消息 #

提交模板以供审批 #

使用您已获批的模板 #

估算成本 #

发起广播 #

为什么发起会被拒绝 #

暂停和恢复 #

在低参与度暂停后继续发送 #

复制广播 #

删除广播 #

镜像经典营销活动的广播 #

错误 #

后续步骤 #

广播 API

如何组合发送任务

广播对象

您设置的字段

平台维护的字段

状态

创建广播

列出广播

获取广播

更新广播

开场消息

提交模板以供审批

使用您已获批的模板

估算成本

发起广播

为什么发起会被拒绝

暂停和恢复

在低参与度暂停后继续发送

复制广播

删除广播

镜像经典营销活动的广播

错误

后续步骤