create-campaign

Vapi アウトバウンドキャンペーン

連絡先、ライフサイクル、結果をまとめて管理する必要がある、継続的なアウトバウンド実行にはキャンペーンを使用します。キャンペーンを作成すると、すぐに開始するか、スケジュールが設定されます。下書きや別途の開始操作はありません。

現在の公開 API では /v2/campaign を使用します。バージョン指定のない /campaign エンドポイントはレガシーであり、動作が異なります。新しい連携には /v2/campaign を使用し、既存のレガシー連携の保守をユーザーから明示的に依頼された場合に限り、/campaign を使用してください。

ソースと安全に関するルール

• 実際に使用するペイロードは、最新の Vapi ドキュメント MCP、キャンペーンのドキュメント、または公開 API リファレンスで確認してください。/v2/campaign からレガシーの /campaign の動作へ、黙って切り替えないでください。
• 秘密 API キーは信頼できるサーバーでのみ使用してください。VAPI_API_KEY から読み取り、表示したり、チャットで尋ねたり、クライアント側のコード、例、ログ、コミット済みファイルに含めたりしないでください。
• 電話番号、氏名、連絡先の変数、通話記録、文字起こし、録音は機密情報として扱ってください。ユーザーが特定の記録を必要としていない限り、件数と匿名化したサンプルを報告してください。
• リソース ID、発信先、同意、スケジュール、タイムゾーン、キャンペーンの状態、カウンター、通話結果を決して捏造しないでください。保存済みリソースは、完全一致する ID または曖昧さのない API 結果で特定してください。
• キャンペーンの開始により、実際の料金が発生する通話が行われる場合があります。実際に作成または複製する前に、対象、発信番号、対象者数、実施時刻、同時実行数、Webhook の動作を確認してください。ユーザーの現在の指示で、その実行が明確に許可されている場合を除き、確認を得てください。
• 法的な判断は行わないでください。すべての発信先と宛先に適用される同意、発信者識別、録音、オプトアウト、発信禁止時間、テレマーケティングの要件を確認するようユーザーに伝えてください。該当する場合は、Vapi の電話消費者保護法（TCPA）に関する同意ガイダンスを使用してください。
• POST /v2/campaign のタイムアウトや曖昧な応答は、失敗を意味するとは限りません。再試行する前に、対象者へ二重に発信しないよう、目的のキャンペーンが存在するか検索してください。

手順

1. API と実行モードを選択します。

   • キャンペーンレベルのライフサイクル、レポート、キャンセル、複製、Webhook が不要な単一の通話や簡単な単発バッチには、POST /call と create-call スキルを使用してください。
   • 下書き、説明、レビュー、準備を求められた場合は、Vapi を呼び出さずにプラン、CSV、ペイロード、実装を提示してください。
   • VAPI_API_KEY を利用でき、作成、複製、キャンセル、アーカイブを求められた場合に限り、実際の API 操作を行ってください。

2. 発信者と発信番号を特定します。

   • 保存済みの assistantId または squadId をちょうど 1 つ選択してください。新しいキャンペーンに非推奨の Workflows を使用しないでください。
   • 発信に対応した phoneNumberId を 1 つ特定してください。Vapi Free Numbers ではキャンペーンを開始できません。現在の /v2/campaign API は、複数の発信番号にわたるレガシーの dialPlan によるルーティングをサポートしていません。
   • 開始前にアシスタントまたは squad を確認してください。プロンプト、ツール、変数、通話終了時の動作、公開済みの設定が、このアウトバウンドのユースケースに合っていることを確認してください。
   • キャンペーン通話を処理する可能性のある各アシスタントに、留守番電話への対応方法を 1 つ設定してください。アシスタント制御の留守番電話ツールか、組み込みの留守番電話検出のいずれかを使い、両方は使用しないでください。規模を拡大する前に、代表的な留守番電話と着信スクリーニングの経路をテストしてください。

3. 連絡先を準備して検証します。

   • 連絡先は1件から10,000件まで指定できます。+14155550100のようなE.164形式の番号を推奨します。APIリクエストで意図的にE.164形式以外のSIPトランク宛先を指定する場合は、その顧客に対してnumberE164CheckEnabled: falseを設定する必要があります。番号には、先頭に任意で+を付け、その後に英字または数字のみを含めてください。DashboardのCSVインポーターではこの顧客単位のフラグを設定できないため、その方法ではE.164形式の番号を使用してください。
   • Dashboard用CSVでは、小文字のnumber列が必須です。小文字のname列は任意です。値が入力されたその他すべての列は、大文字と小文字が区別される動的変数になります。ヘッダーには小文字のsnake_caseを推奨します。
   • CSVファイルは、Dashboardで定められた5 MBの上限以内にしてください。空欄または形式不正の行は拒否し、重複は確認のために提示してください。宛先を黙って削除または統合しないでください。
   • APIリクエストでは、アシスタントキャンペーンの場合はassistantOverrides.variableValuesに、スクワッドキャンペーンの場合はsquadOverrides.variableValuesに連絡先ごとの値を指定してください。任意のソース列を無関係な設定フィールドにコピーしないでください。
   • 各連絡先の変数データは、シリアライズ後の合計が100,000文字未満になるようにしてください。呼び出し元が参照するすべての変数が存在するか、意図したフォールバック動作があることを確認してください。

4. タイミングと同時実行数を設定します。

   • 空き容量ができ次第すぐに配信を開始する新規キャンペーンでは、schedulePlanを省略してください。
   • 配信時間帯を予約する場合は、schedulePlan.earliestAtと任意のlatestAtをISO 8601形式の日時で指定してください。ユーザーから現地時刻が示された場合は、IANAタイムゾーンを特定して変換し、現地時刻とISO形式の値の両方を表示してください。
   • latestAtがearliestAtより後であることを確認してください。Dashboardでは、最大7日先まで、15分刻みでスケジュールできます。Dashboard以外で実装する場合は、現在のAPI制約を再確認してください。
   • maxConcurrencyは、組織で利用可能な同時実行数以下に設定してください。この値はキャンペーンの同時実行数を制限しますが、枠を確保したり、組織で共有される通話容量を増やしたりするものではありません。
   • 対象全体の配信に十分な時間を確保してください。空き容量待ちの連絡先は最大1時間まで再試行されることがありますが、latestAtに達するとそれより早く再試行が停止します。

5. 必要な場合にのみキャンペーンのWebhookを設定します。

   • predialPlanまたはserverMessagesを使用する前に、serverを設定してください。インラインのシークレットより保存済みの認証情報を優先し、意図したタイムアウトとバックオフの計画を設定してください。
   • 各連絡先への発信直前に同期的な確認を行うには、predialPlan: { "enabled": true }を使用してください。エンドポイントは、Boolean型のeligibleを含むJSONを返す必要があります。値がfalseの場合はその連絡先をスキップし、タイムアウト、2xx以外のステータス、または不正なJSONの場合はcontact.predial-failedが発生します。
   • 選択したキャンペーンおよび連絡先のライフサイクルイベントを非同期で受信するには、serverMessagesを使用してください。受信側は冪等にし、イベントの順序に依存しないでください。
   • キャンペーンイベントには、通話の全アーティファクトは含まれません。統合で文字起こし、録音、または分析も必要な場合は、該当するアシスタントにend-of-call-reportを設定し、callIdでレコードを結合してください。

6. リクエストを作成して確認します。

   • 新規キャンペーンでは、name、assistantIdまたはsquadIdのいずれか一方、phoneNumberId、空でないcustomers配列、およびmaxConcurrencyを含めてください。
   • 複製する場合は、nameとduplicateFromCampaignIdを含め、意図した置き換え項目だけを送信してください。元の対象を引き継ぐにはcustomersを省略してください。customers配列を指定すると、元の対象が置き換えられます。
   • キャンペーン単位のassistantOverridesまたはsquadOverrides、schedulePlan、server、serverMessages、predialPlanは、意図がある場合にのみ追加してください。
   • 検証済みのREST形式、複製のセマンティクス、ページネーション、ライフサイクルリクエストについては、キャンペーンAPIリファレンスを参照してください。
   • 本番配信の開始前に、解決された発信元と電話番号、マスキングしたサンプルを含む対象件数、現地時刻とISO形式の時刻、最大同時実行数、Webhookによる副作用、および発信がすぐに開始されるかどうかを表示してください。通常の確認出力では、連絡先のペイロード全体を公開しないでください。

7. 一度作成して、必ず確認します。

   • POST /v2/campaign を1回送信します。返されたキャンペーン ID を永続的な識別子として扱います。
   • 作成に成功したと判断する前に、GET /v2/campaign/{id}?includeCounters=true で再取得します。実際のステータスとスケジュールを報告してください。作成されたからといって、連絡先に到達したことの証明にはなりません。
   • 作成リクエストが判然としないタイムアウトまたは 5xx を返した場合は、絞り込んだサポート対象のフィルターと作成時刻を手掛かりに GET /v2/campaign を使ってキャンペーンを探します。POST を自動的に再送信しないでください。

8. 連絡先の情報をもとに調査、診断します。

   • キャンペーンを includeCounters=true で取得します。保留中、ディスパッチ済み、完了、失敗、スキップ、発信前失敗の件数には contactCounters を使用し、応答状況の分析には callMetrics.dialed と callMetrics.connected を使用します。
   • GET /v2/campaign/{id}/contacts を取得し、必要に応じてページネーションを行います。各対象者の実際の状況を確認するには、連絡先のステータスを正としてください。
   • スキップされた連絡先、または発信前に失敗した連絡先には、通話が発信されていないため通話 ID がない場合があります。実際の callId がある場合は、その通話を取得し、根本原因を提案する前に終了理由、トランスクリプト、録音、分析、ログを確認します。
   • キャンペーンのディスパッチ問題、発信前の適格性チェックの失敗、電話接続の失敗、ボイスメールの結果、アシスタントの動作を区別します。カウンターだけでは原因を特定できません。

9. 再実行または互換性のある設定への置き換えには複製します。

   • キャンペーンは作成後に変更できません。発信者、連絡先、スケジュール、同時実行数、Webhook 設定にパッチを適用しないでください。
   • duplicateFromCampaignId と新しい name を指定して、新しいキャンペーンを作成します。省略した設定と連絡先はソースからコピーされ、指定したフィールドはソースの値を上書きします。また、customers を指定すると、コピーされた連絡先が置き換えられます。ソースも現在の /v2/campaign API を使用している必要があります。
   • 複製では、継承したすべてのフィールドを解除できるわけではありません。特に、assistantId と squadId を切り替えると、以前の相互排他関係にある発信者が継承され、リクエストが無効になります。発信者の種類を変更する場合や、継承したオプションを置き換えるのではなく削除する必要がある場合は、新しいキャンペーンを作成してください。
   • 開始前に、継承したすべてのフィールドを確認します。期限切れのスケジュールを継承するのではなく複製をほぼ即時に実行するには、リクエストの直前に schedulePlan.earliestAt を生成し、転送中およびサーバー検証中も有効な十分な猶予を設けます。たとえば、現在の UTC 時刻に 60 秒を加えます。結果として生じる遅延を明示してください。
   • 複製も新規キャンペーンと同様に、同じ承認と二重発信防止策が必要な、別の本番開始として扱います。

10. キャンセルまたはアーカイブは慎重に行います。

• スケジュール済みまたは実行中のキャンペーンを停止するには、{ "status": "cancelled" } のみを指定して PATCH /v2/campaign/{id} を送信します。保留中の処理は停止しますが、進行中の通話は完了する場合があります。キャンセルはそのキャンペーンに対して取り消せません。
• 再取得して、終了状態と endedReason を確認します。キャンセルによってすでに発信した通話が取り消されるかのように説明しないでください。
• DELETE /v2/campaign/{id} は、キャンペーンの記録を完全に消去するのではなくアーカイブします。キャンペーンがアクティブな場合は、先にキャンセルされます。ユーザーから別途、アクティブなキャンペーンの一覧から削除するよう依頼された場合に限り、アーカイブしてください。

障害への対応

• 400：拒否されたフィールドを報告し、現在の /v2/campaign スキーマと照合します。リクエスト形式に関する明確な問題を1つ修正し、安全な再試行は最大1回にとどめます。
• 401 または 403：認証、スコープ、利用資格、サブスクリプションの凍結、権限の問題として処理を停止します。
• 404：見つからないキャンペーン、アシスタント、スカッド、または電話番号の ID を正確に報告します。
• 409：キャンペーンを再取得します。不変または終了済みのライフサイクルに関する競合がある場合は、複製するか、それ以上の操作を行わないでください。パッチを再送信してはいけません。
• 429 または 5xx：サービスの状態を報告します。重複したキャンペーンが作成されていないことを確認するまでは、キャンペーン作成を再試行しないでください。
• 一部のみ完了した場合：キャンペーンを保持し、実際の連絡先ごとの結果を報告します。残りの対象者を自動的に削除、再発信、置き換えしないでください。

出力内容

リクエストに必要な内容のみを返します。

• モード：plan、payload、launch、inspect、duplicate、cancel、archive、diagnose
• 解決済みの発信者、発信番号、連絡先件数、マスキング済みのサンプル
• ローカル時間と ISO 形式のスケジュール、最大同時実行数、共有容量に関する注意事項
• ユーザーによる確認が引き続き必要な同意事項と発信可能時間帯の前提
• Webhook と発信前の動作、および残っているライブな副作用
• 要求された場合は、保存可能な CSV、JSON、またはコード
• ライブ操作後のキャンペーン ID、検証済みステータス、カウンター、連絡先ごとの結果、通話 ID
• 未解決の失敗、証拠、安全に実施できる最小限の次のアクション

公開ソース

• キャンペーンの概要
• キャンペーンのクイックスタート
• キャンペーンの連絡先データ
• キャンペーンのスケジュールとライフサイクル
• キャンペーンのボイスメールと通話スクリーニング
• キャンペーンの Webhook
• キャンペーン API リファレンス