# Broadcasts API

**ブロードキャスト**とは、オーディエンス、開始メッセージ、1つのチャネル、およびスケジュールという、1回のアウトバウンド送信を指します。オプションで、返信を処理するAIエージェントを指定することもできます。Broadcasts APIを使用すると、ダッシュボードではなく独自のコードからこれらの送信を作成、価格設定、開始、監視できます。製品そのものについては、[Broadcastsガイド](../broadcasts/broadcasts.md)を参照してください。

- **ベースURL** — `https://api.youraiconnector.com/v1`
- **認証** — APIキー（[認証](authentication.md)を参照）
- **エラーとページネーション** — [エラーとページネーション](errors-and-pagination.md)を参照

以下のすべての例では、cURLでの `?apiKey=` クエリ形式と、JavaScriptおよびPythonでの `X-API-Key` ヘッダーを示しています。どちらの方法もすべてのエンドポイントで使用可能です。

> **APIエクスプローラーについて** このページのすべてのエンドポイントは公開されているOpenAPI仕様に含まれているため、[APIエクスプローラー](reference.md)で正確なフィールドを確認し、ライブリクエストを実行できます。


---

## 送信の構成方法

ブロードキャストの送信は、1回ではなく4回の呼び出しで行われます。

1. **作成:** オーディエンス、チャネル、スケジュールを指定してブロードキャストを作成します。最初は `Draft` として開始されます。
2. **開始メッセージの設定:** WhatsApp Businessの場合、これは承認のためにテンプレートを送信する（または既に承認済みのテンプレートを選択する）ことを意味します。他のすべてのチャネルでは、プレーンテキストとなります。
3. **コストの見積もり:** 何かを行う前に価格を確認したい場合（オプション）。
4. **開始:** 開始を実行すると、オーディエンス、メッセージ、テンプレートの承認、接続された送信者などの完全なチェックが行われ、送信が開始されるか、不足している情報が正確に通知されます。

開始（launch）を呼び出すまで、何も送信されません。

---

## ブロードキャストオブジェクト

```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
}
```

**タイムスタンプはエポックミリ秒**（`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`。ブロードキャストには必ず1つのチャネルが必要です。同じ内容を別の場所へ送信するには、[別のチャネルに複製](#duplicate-a-broadcast)してください。`tiktok` と `skool` は返信専用であり、ブロードキャストには使用できません。 |
| `agent_id` | 返信に応答するAIエージェント。`null` のままにすると、返信はチームの受信トレイに届きます。 |
| `list_id` | 送信先の連絡先リスト。これがAPIからオーディエンスを設定する方法です。リストの作成と入力については[連絡先](contacts.md)を参照してください。 |
| `list_name` | ブロードキャストの横に表示される表示名。装飾的なものです。 |
| `send_to_new_list_members` | `true` はブロードキャストを有効に保つため、後からリストに追加されたユーザーも開始メッセージを受け取ります。 |
| `whats_app_template` | 開始メッセージ。WhatsApp Businessでは承認済みのテンプレートを使用し、他のすべてのチャネルではその `body` がプレーンな開始テキストとして使用されます。手動ではなく、[テンプレートエンドポイント](#the-opening-message)を通じて設定してください。 |
| `opener_media` | 開始メッセージと共に送信される画像または動画。常にオブジェクト全体を送信してください（削除する場合は `null` を送信）。内部の個別のキーを書き込むと拒否されます。SMSではサポートされていません。 |
| `execution_date` | 送信タイミング。ISO 8601タイムスタンプまたはエポックミリ秒を送信します。未来の日付を指定すると送信がスケジュールされ、省略（または過去の日付を使用）すると開始した直後に送信されます。 |
| `drip_mode` | `true` は、一度にすべて送信するのではなく、時間をかけてバッチ単位で送信を調整します。 |
| `time_critical` | `true` は、50件以上の連絡先がある場合に自動的に有効になる自動調整を無効にします。すぐにメッセージを必要とするアクティブなオーディエンス向けです。チャネル自体の1日の送信制限を解除するものではありません。 |
| `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**

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

**レスポンス** (`201`)

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

---

## ブロードキャストを一覧表示する

`GET /broadcasts` — アカウント内のすべてのブロードキャストを、新しい順に返します。

**クエリパラメータ**

| パラメータ | 必須 | 説明 |
|---|---|---|
| `status` | いいえ | 指定したステータスのブロードキャストのみを返します（例: `Sending`）。[ステータステーブル](#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"]
```

**レスポンス** (`200`)

```json
{ "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` は進行に合わせて更新されます。

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

アカウントに存在しないブロードキャストを指定すると、`404` が返されます。

---

## ブロードキャストを更新する

`PUT /broadcasts/{broadcastId}` — 変更したいフィールドのみを送信します。ドット表記のパスを使用して、ネストされたオブジェクト内の単一のキーを指定することもできます（例: `"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" }),
});
```

空のボディを送信すると `400` が返されます。以下の2つのルールに注意してください。

- **`opener_media` はすべて置換されます。** オブジェクト全体を送信するか、添付ファイルを削除するために `null` を送信してください。添付ファイル内のドットパス（`opener_media.name`）は、不完全な更新により存在しないファイルを参照する可能性があるため、`400` で拒否されます。
- **ステータスは編集できません。** [開始](#launch-a-broadcast)、[一時停止](#pause-and-resume)、[再開](#pause-and-resume)を使用してください。

---

## 最初のメッセージ

すべてのブロードキャストには、`whats_app_template` にオープナーが含まれています。これが何を意味するかはチャネルによって異なります。

- **WhatsApp Business** — WhatsAppによって承認されたテンプレートである必要があります。以下の2つのエンドポイントのいずれかを使用してください。
- **その他のすべてのチャネル** (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` | いいえ | プレースホルダー名（出現順）。省略すると本文から読み取られます。通常は各連絡先から送信内容が入力されるため、省略するのが一般的です。 |

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

**レスポンス** (`200`)

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

`template_status` はWhatsAppのステータスを示します：レビュー中は `pending`、使用可能な場合は `approved`、拒否された場合は `rejected` となります。WhatsApp以外のチャネルでは、`template_sid: null` を伴う `approved` として直接返されます（レビューは不要です）。

実行を妨げる要因:

- 前のテンプレートがまだレビュー中の状態で送信すると、`400` が返されます。まずは決定を待ってください。
- 現在承認されているテンプレートを編集する場合、新しいテンプレートが戻るまでは承認済みのものが有効なままとなるため、実行中のブロードキャストでオープナーが失われることはありません。
- Meta経由で直接接続されたWhatsApp番号では、画像や動画が添付されたブロードキャストは送信できません（`400`）。添付ファイルは、管理対象のWhatsApp BusinessレーンおよびWhatsApp Webでサポートされています。

### 承認済みのテンプレートを使用する

`POST /broadcasts/{broadcastId}/template/select` — 承認済みのテンプレートを[テンプレートライブラリ](templates.md)からブロードキャストにコピーするため、待機時間は発生しません。

| フィールド | 必須 | 説明 |
|---|---|---|
| `template_id` | はい | アカウント上の承認済みテンプレートのID。 |

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

**レスポンス** (`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"
}
```

承認はライブラリレコードから弊社側で検証されます。送信するのはIDのみです。ブロードキャストがWhatsAppの下書きではない場合、テンプレートが承認されていない場合、オープナーではなくフォローアップテンプレートである場合、またはブロードキャストに添付ファイルがある場合（ライブラリテンプレートはテキストのみです）、`400` が返されます。アカウントに存在しないテンプレートIDを指定すると、`404` が返されます。

---

## コストを見積もる

`POST /broadcasts/{broadcastId}/estimate-cost` — 送信を確定する前に価格を見積もります。`whatsapp` および `sms` ブロードキャストで利用可能です。その他のチャネルでは `400` が返されます。見積もりにはオーディエンス数が含まれるため、ブロードキャストには `list_id` が必要です。

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

**WhatsAppの応答** (`200`) — 送信先国別のクレジット内訳:

```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
  }
}
```

**SMS応答** (`200`) — 米ドル。お客様自身のTwilioアカウントに対するTwilioのライブ価格に基づきます：

```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
  }
}
```

**番号を表示する前に `billing_mode` をお読みください。** 誰に請求されるかが記載されています：

| `billing_mode` | 支払い元 | 数値の意味 |
|---|---|---|
| `credits` | お客様の <span data-t="appName">Your AI Connector</span> アカウント | `totalTemplateCost` および国別の数値はクレジットです。 |
| `twilio_direct` | お客様自身のTwilioアカウント | `estimatedCostUsd` はTwilioがお客様に請求する金額です。 |
| `meta_waba_direct` | Metaが請求するお客様自身のWhatsApp Businessアカウント | すべてのクレジット数値は `null` として返されます。「無料」と誤解されないよう意図的なものです。国および連絡先のカウントは正確なままです。 |

Twilioの認証情報が接続されていないSMSでもセグメント数は返されますが、`estimatedCostUsd: 0` となります。参照すべき価格設定がないためです。

---

## ブロードキャストを開始する

`POST /broadcasts/{broadcastId}/launch`

開始時にはすべてがチェックされ、その後にのみブロードキャストが進められます。部分的な開始はありません。開始されるか、何も変更されずに理由を示すエラーが返されるかのいずれかです。

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

**レスポンス** (`200`)

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

`status` はブロードキャストが着地した場所です：

- `Scheduled` — `execution_date` は未来の日時です。
- `Sending` — 今すぐ開始されました。
- `Pending Approval` — WhatsAppテンプレートはまだ審査中です。テンプレートが承認されると自動的に送信されます。再度開始（launch）を呼び出さないでください。

`Draft`（またはテンプレートがその後承認された `Pending Approval` ブロードキャスト）のみが開始可能です。それ以外は `400` が返されます。

### 開始が拒否される理由

これらはすべて `400` として、分かりやすい `error` メッセージと共に返されます：

| 問題 | 修正方法 |
|---|---|
| 宛先なし | 開始前に `list_id` を設定（または連絡先を添付）してください。 |
| 開始メッセージなし | オープナーを設定してください。 [開始メッセージ](#the-opening-message) を参照してください。 |
| SMSへの添付ファイル | SMSは画像や動画を送信できません。添付ファイルを削除するか、ブロードキャストをWhatsAppに移動してください。 |
| 添付ファイルが承認済みテンプレートと一致しない | WhatsAppではメディアは承認済みテンプレート内に存在するため、後から添付ファイルを入れ替えるにはテンプレートの再提出が必要です。 |
| テンプレートが拒否されました | メッセージを書き直して再度提出してください。 |
| テンプレートが未提出 | 先に提出（または承認済みテンプレートを選択）してください。 |
| テンプレートは承認済みだがWhatsAppアカウントに見当たらない | 通常、番号の接続が完了する前に承認されたテンプレートです。再度提出してください。 |
| チャネルの送信元が接続されていない | 先にチャネルを接続してください。[チャネル](channels.md) を参照してください。 |
| 返信専用チャネル | TikTokとSkoolはビジネス側からの会話開始を許可していないため、ブロードキャストはできません。 |
| すでに準備済み | ブロードキャストにはすでに送信予定があります。再度開始する前に一時停止してください。 |
| 承認待ち | テンプレートが承認されると自動的に送信されます。 |
| WhatsApp BusinessアカウントがMetaによってブロックされている | Metaがお客様自身のWhatsApp Businessアカウントでのビジネス主導の会話を停止しました。通常は支払い方法の問題です。Metaのビジネスマネージャで修正してください。 |
| クラシックキャンペーンから開始された | キャンペーンエディタから開始してください。[ブロードキャストにおけるクラシックキャンペーン](#broadcasts-that-mirror-a-classic-campaign) を参照してください。 |

---

## 一時停止と再開

`POST /broadcasts/{broadcastId}/pause` は `Sending` または `Scheduled` ブロードキャストを停止し、キューに入れられたものをすべて破棄します。

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

`Pending Approval` ブロードキャストを一時停止すると、代わりに `Draft` に戻ります。スケジュールがまだ設定されていないため、再開先が存在しないためです。その他のステータスでは `400` が返されます。

`POST /broadcasts/{broadcastId}/resume` は `Paused` ブロードキャストを再開します：

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

**レスポンス** (`200`)

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

`Sending` に再開するか、その `execution_date` がまだ未来であれば `Scheduled` に戻ります。`Paused` ブロードキャストのみ再開可能です。

---

## エンゲージメント低下による一時停止後も送信を継続する

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

ブロードキャストはバッチ単位で送信されますが、次のバッチを開始する前に、各バッチに対して何人が返信したかを測定します。ほとんど返信がない場合、ブロードキャストは自動的に一時停止します。反応のない相手に送信し続けることは、電話番号がフィルタリングされたりブロックされたりする最も早い原因となるためです。ダッシュボードにある **[とにかく続行]** ボタンがこれに該当します。

一時停止の原因となった返信率はブロードキャストが停止している間は変化しないため、単純な [再開](#pause-and-resume) を実行しても、次のチェックで再び一時停止されてしまいます。このエンドポイントは、とにかく送信を継続するという決定を行うためのものです。このエンドポイントは、その特定のブロードキャストに対するオーバーライドを記録し、エンゲージメント低下が原因で一時停止されていた場合は、同じ呼び出しで一時停止を解除します。

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

**レスポンス** (`200`)

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

- `resumed: true` — ブロードキャストはエンゲージメント低下により一時停止されていましたが、現在は実行中です。`status` は再開先です。
- `resumed: false` — 一時停止は解除されていません。オーバーライドは将来のチェックのために記録されただけです。これは、ブロードキャストが一時停止されていなかった場合、または別の理由（手動で一時停止した、送信制限に達した、送信エラーが多発したなど）で一時停止されていた場合に返されます。これらの停止はここでは解除されません。原因に対処した後、ご自身で再開してください。

このオーバーライドはこのブロードキャストにのみ適用されます。アカウント設定ではなく、二度呼び出しても安全です。

---

## ブロードキャストを複製する

`POST /broadcasts/{broadcastId}/duplicate` — オーディエンス、メッセージ、設定を新しい `Draft` にコピーします。前回の実行に関するすべての情報（カウンター、バッチ、スケジュール、返信統計）はリセットされます。

| フィールド | 必須 | 説明 |
|---|---|---|
| `to_channel` | いいえ | 別のチャネルでコピーを作成します。これにより、同じ内容を2つのチャネルで送信できます（ブロードキャストは常に1つのチャネルにのみ属します）。 |

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

**レスポンス** (`201`)

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

コピーは、有効なWhatsApp承認を継承しません。WhatsAppのコピーではテンプレートの確認が必要となり、別のチャネルへのコピーではテンプレートが削除され、テキストはプレーンな開始メッセージになります。SMSへのコピーでは、SMSが添付ファイルを送信できないため、添付ファイルも削除されます。

---

## ブロードキャストを削除する

`DELETE /broadcasts/{broadcastId}`

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

`Sending` または `Scheduled` ブロードキャストは `400` で拒否されます。先に一時停止してください。

---

## クラシックキャンペーンをミラーリングするブロードキャスト

メッセージを送信するクラシックキャンペーンもブロードキャストに表示され、APIはネイティブブロードキャストと並んでそれらを返します（これらには `source_campaign_id` が付与されます）。キャンペーンが管理権限を保持しているため、動作が少し異なります。

- **編集**: オーディエンス、メッセージ、スケジュールの編集は機能し、キャンペーンに書き込まれます。
- **チャネル、返信エージェント、添付ファイル、およびすべての実行カウンターは読み取り専用です**。変更しようとすると `400` が返されます。これらはキャンペーン側で変更してください。
- **開始 (Launch)**: キャンペーンエディターへのリンクを含む `400` を返します。
- **一時停止と再開**: 機能し、キャンペーンに対して実行されます。
- **削除**: `400` を返します。代わりにキャンペーンを削除してください。そうすれば、そのブロードキャストエントリも一緒に削除されます。
- **複製**: 独立したネイティブブロードキャストが作成されます。これが、実績のあるキャンペーンを移行するためのサポートされている方法です。

---

## エラー

失敗したリクエストは、以下のステータスとともに `{"success": false, "error": "<message>"}` を返します。

| ステータス | 意味 |
|---|---|
| `400` | リクエストまたはブロードキャストの状態に問題があります（フィールドの欠落、無効な添付ファイル、または現在のブロードキャストステータスでは許可されていない開始/一時停止/再開/削除など）。`error` メッセージに理由が記載されています。 |
| `401` | APIキーが欠落しているか無効です。 |
| `403` | ご契約プランにはAPIアクセスが含まれていません。 |
| `404` | アカウントにそのようなブロードキャスト（またはテンプレート選択時にそのようなテンプレート）は存在しません。 |
| `429` | レート制限に達しました。時間を置いて再試行してください。 |
| `500` | 弊社側で問題が発生しました。少し待ってから再試行してください。 |

---

## 次のステップ

- [ブロードキャストガイド](../broadcasts/broadcasts.md) — ペーシングや安全動作など、これらのエンドポイントの背景にある製品について
- [連絡先API](contacts.md) — ブロードキャストの送信先リストを作成する
- [テンプレートAPI](templates.md) — 選択可能な承認済みWhatsAppテンプレートを管理する
- [Webhook API](webhooks.md) — ポーリングの代わりに `Broadcast Started` と `Broadcast Completed` をサブスクライブする