broadcast-campaign

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Broadcast Campaign

广播营销活动

When to Use

使用场景

Use this skill when building code to send messages to multiple recipients in a campaign — including bulk email. Covers the full broadcast lifecycle from creation to monitoring.

当你需要编写代码向活动中的多个接收者发送消息（包括批量邮件）时，可使用此技能。覆盖从创建到监控的完整广播生命周期。

Broadcast Lifecycle

广播生命周期

draft -> pending_review -> approved -> sending -> completed
                        -> rejected -> (edit) -> pending_review (retry, max 3)
                        -> rejected -> escalated (manual review by Zavu team)
                        -> rejected_final
         approved -> scheduled -> sending -> completed
         sending -> paused (can resume)
         (any active) -> cancelled
         (any) -> failed (permanent failure)

draft -> pending_review -> approved -> sending -> completed
                        -> rejected -> (edit) -> pending_review (retry, max 3)
                        -> rejected -> escalated (manual review by Zavu team)
                        -> rejected_final
         approved -> scheduled -> sending -> completed
         sending -> paused (can resume)
         (any active) -> cancelled
         (any) -> failed (permanent failure)

Step-by-Step Workflow

分步工作流程

1. Create Broadcast

1. 创建广播活动

typescript

const result = await zavu.broadcasts.create({
  name: "Black Friday Sale",
  channel: "sms", // smart | sms | sms_oneway | whatsapp | telegram | email | instagram | voice
  text: "Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20",
});
const broadcastId = result.broadcast.id; // brd_xxx

Python:

python

result = zavu.broadcasts.create(
    name="Black Friday Sale",
    channel="sms",
    text="Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20",
)
broadcast_id = result.broadcast.id

Go:

result, err := client.Broadcasts.Create(context.TODO(), zavudev.BroadcastCreateParams{
    Name:    zavudev.String("Black Friday Sale"),
    Channel: zavudev.String("sms"),
    Text:    zavudev.String("Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20"),
})
broadcastID := result.Broadcast.ID

Ruby:

ruby

result = client.broadcasts.create(
    name: "Black Friday Sale",
    channel: "sms",
    text: "Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20",
)
broadcast_id = result.broadcast.id

PHP:

php

$result = $client->broadcasts->create([
    'name' => 'Black Friday Sale',
    'channel' => 'sms',
    'text' => 'Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20',
]);
$broadcastId = $result->broadcast->id;

typescript

const result = await zavu.broadcasts.create({
  name: "Black Friday Sale",
  channel: "sms", // smart | sms | sms_oneway | whatsapp | telegram | email | instagram | voice
  text: "Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20",
});
const broadcastId = result.broadcast.id; // brd_xxx

Python:

python

result = zavu.broadcasts.create(
    name="Black Friday Sale",
    channel="sms",
    text="Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20",
)
broadcast_id = result.broadcast.id

Go:

result, err := client.Broadcasts.Create(context.TODO(), zavudev.BroadcastCreateParams{
    Name:    zavudev.String("Black Friday Sale"),
    Channel: zavudev.String("sms"),
    Text:    zavudev.String("Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20"),
})
broadcastID := result.Broadcast.ID

Ruby:

ruby

result = client.broadcasts.create(
    name: "Black Friday Sale",
    channel: "sms",
    text: "Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20",
)
broadcast_id = result.broadcast.id

PHP:

php

$result = $client->broadcasts->create([
    'name' => 'Black Friday Sale',
    'channel' => 'sms',
    'text' => 'Hi {{name}}, check out our Black Friday deals! Code: FRIDAY20',
]);
$broadcastId = $result->broadcast->id;

Channel Options

渠道选项

Channel	Description
`smart`	Per-contact intelligent routing
`sms`	SMS to all contacts
`sms_oneway`	One-way SMS (no replies)
`whatsapp`	WhatsApp (requires template for non-window contacts)
`telegram`	Telegram
`email`	Email (requires KYC, needs `emailSubject` ) — recommended path for bulk email
`instagram`	Instagram Direct
`voice`	Voice call with text-to-speech

渠道	描述
`smart`	针对每个联系人的智能路由
`sms`	向所有联系人发送短信
`sms_oneway`	单向短信（不接收回复）
`whatsapp`	WhatsApp（对非窗口联系人需使用模板）
`telegram`	Telegram
`email`	邮件（需完成KYC，需指定 `emailSubject` ）——批量邮件推荐渠道
`instagram`	Instagram私信
`voice`	带文本转语音功能的语音通话

Message Types

消息类型

Type	Description
`text`	Plain text (default)
`image`	Image with optional caption
`video`	Video message
`audio`	Audio message
`document`	Document file
`template`	WhatsApp pre-approved template

类型	描述
`text`	纯文本（默认）
`image`	图片（可附带说明文字）
`video`	视频消息
`audio`	音频消息
`document`	文档文件
`template`	WhatsApp预审批模板

Email Broadcast (with HTML body)

邮件广播（含HTML正文）

For bulk email campaigns, use

channel: "email"

with an HTML body. This is the recommended way to send mass email through Zavu.

typescript

const result = await zavu.broadcasts.create({
  name: "Newsletter",
  channel: "email",
  emailSubject: "Special offer for {{name}}",
  text: "Hi {{name}}, check out our latest sale!",   // plain text fallback
  emailHtmlBody: "<h1>Hi {{name}}!</h1><p>Check out our latest sale.</p>",
  metadata: { campaign_id: "camp_123", region: "US" },
});

对于批量邮件活动，请使用

channel: "email"

并搭配HTML正文。这是通过Zavu发送批量邮件的推荐方式。

typescript

const result = await zavu.broadcasts.create({
  name: "Newsletter",
  channel: "email",
  emailSubject: "Special offer for {{name}}",
  text: "Hi {{name}}, check out our latest sale!",   // 纯文本备选内容
  emailHtmlBody: "<h1>Hi {{name}}!</h1><p>Check out our latest sale.</p>",
  metadata: { campaign_id: "camp_123", region: "US" },
});

2. Add Contacts (batch, max 1000/request)

2. 添加联系人（批量，每次请求最多1000个）

typescript

const result = await zavu.broadcasts.contacts.add({
  broadcastId: broadcastId,
  contacts: [
    { recipient: "+14155551234", templateVariables: { name: "John" } },
    { recipient: "+14155555678", templateVariables: { name: "Jane" } },
  ],
});
console.log(result.added, result.duplicates, result.invalid);

typescript

const result = await zavu.broadcasts.contacts.add({
  broadcastId: broadcastId,
  contacts: [
    { recipient: "+14155551234", templateVariables: { name: "John" } },
    { recipient: "+14155555678", templateVariables: { name: "Jane" } },
  ],
});
console.log(result.added, result.duplicates, result.invalid);

3. Send (triggers AI content review)

3. 发送（触发AI内容审核）

typescript

// Send immediately
await zavu.broadcasts.send({ broadcastId });

// Or schedule
await zavu.broadcasts.send({
  broadcastId,
  scheduledAt: "2024-01-15T10:00:00Z",
});

typescript

// 立即发送
await zavu.broadcasts.send({ broadcastId });

// 或定时发送
await zavu.broadcasts.send({
  broadcastId,
  scheduledAt: "2024-01-15T10:00:00Z",
});

4. Monitor Progress

4. 监控进度

typescript

const progress = await zavu.broadcasts.progress({ broadcastId });
console.log(`${progress.percentComplete}% complete`);
console.log(`Delivered: ${progress.delivered}, Failed: ${progress.failed}, Skipped: ${progress.skipped}`);
console.log(`Estimated completion: ${progress.estimatedCompletionAt}`);

Per-contact statuses:

pending

queued

sending

delivered

failed

skipped

(excluded — opted out, duplicate, or invalid).

typescript

const progress = await zavu.broadcasts.progress({ broadcastId });
console.log(`${progress.percentComplete}% complete`);
console.log(`Delivered: ${progress.delivered}, Failed: ${progress.failed}, Skipped: ${progress.skipped}`);
console.log(`Estimated completion: ${progress.estimatedCompletionAt}`);

单联系人状态：

pending

（待处理）、

queued

（已排队）、

sending

（发送中）、

delivered

（已送达）、

failed

（发送失败）、

skipped

（已跳过——退订、重复或无效联系人）。

5. Handle Rejection (if content review fails)

5. 处理审核驳回（若内容审核未通过）

typescript

// Check remaining review attempts
const broadcast = await zavu.broadcasts.get({ broadcastId });
console.log(`Review attempts: ${broadcast.reviewAttempts}/3`);

// Edit content
await zavu.broadcasts.update({
  broadcastId,
  text: "Updated message content with {{name}}",
});

// Retry review (max 3 attempts)
await zavu.broadcasts.retryReview({ broadcastId });

// Or escalate to manual review
await zavu.broadcasts.escalate({ broadcastId });

typescript

// 查看剩余审核重试次数
const broadcast = await zavu.broadcasts.get({ broadcastId });
console.log(`Review attempts: ${broadcast.reviewAttempts}/3`);

// 编辑内容
await zavu.broadcasts.update({
  broadcastId,
  text: "Updated message content with {{name}}",
});

// 重试审核（最多3次）
await zavu.broadcasts.retryReview({ broadcastId });

// 或升级至人工审核
await zavu.broadcasts.escalate({ broadcastId });

Other Operations

其他操作

typescript

// Reschedule
await zavu.broadcasts.reschedule({
  broadcastId, scheduledAt: "2024-01-16T14:00:00Z",
});

// Cancel (pending contacts skipped, queued may still deliver)
await zavu.broadcasts.cancel({ broadcastId });

// List contacts in broadcast
const contacts = await zavu.broadcasts.contacts.list({
  broadcastId, status: "delivered", limit: 100,
});

// Delete (draft only)
await zavu.broadcasts.delete({ broadcastId });

typescript

// 重新定时
await zavu.broadcasts.reschedule({
  broadcastId, scheduledAt: "2024-01-16T14:00:00Z",
});

// 取消（待处理联系人将被跳过，已排队的消息可能仍会送达）
await zavu.broadcasts.cancel({ broadcastId });

// 列出广播活动中的联系人
const contacts = await zavu.broadcasts.contacts.list({
  broadcastId, status: "delivered", limit: 100,
});

// 删除（仅草稿状态的活动可删除）
await zavu.broadcasts.delete({ broadcastId });

Template Variables

模板变量

Use

{{variable_name}}

in broadcast text. Override per-contact via

templateVariables

typescript

await zavu.broadcasts.contacts.add({
  broadcastId,
  contacts: [
    { recipient: "+14155551234", templateVariables: { name: "John", order_id: "ORD-001" } },
  ],
});

在广播文本中使用

{{variable_name}}

。可通过

templateVariables

为单个联系人覆盖变量：

typescript

await zavu.broadcasts.contacts.add({
  broadcastId,
  contacts: [
    { recipient: "+14155551234", templateVariables: { name: "John", order_id: "ORD-001" } },
  ],
});

Constraints

限制条件

Max 1000 contacts per
```
add
```
request (batch for larger lists)
Content goes through AI review before sending
Balance is reserved (estimated cost) when sending
Max 3 review retry attempts, then escalate
Can only update/delete broadcasts in
```
draft
```
status
Cancelling doesn't stop already-queued messages

每次
```
add
```
请求最多添加1000个联系人（更大列表需分批处理）
内容发送前需经过AI审核
发送时会预留余额（预估成本）
最多可重试审核3次，之后需升级至人工审核
仅
```
draft
```
状态的广播活动可更新/删除
取消操作无法停止已排队的消息