channel-setup

チャネルの設定

使用する場面

新しく接続したチャネル（WhatsApp、Telegram、Instagram、Messenger、メール、電話番号）をコードに組み込むときや、API に渡す送信者 ID を決めるときに、このスキルを使用します。

2 層モデル

Zavu には、初心者が混同しがちな 2 つのオブジェクトがあります。

層	内容	所在地
アカウント	プロバイダーへの接続です。WhatsApp Business アカウント、Facebook ページ、Instagram アカウント、Telegram ボット、メールドメイン、電話番号などが該当します	ダッシュボード（Accounts、Phone Numbers）で接続するか、パートナーからの招待を通じて接続します
送信者	アカウントをルーティングする API ハンドルです。Zavu-Sender として渡すもので、Webhook と AI エージェントを保持します	GET /v1/senders

**課金：**料金が発生するのはアカウントです（WhatsApp アカウント、チャネル接続、電話番号）。送信者は無料です。送信者は、アカウントを 1 つの送信 ID の下にまとめて表示するものです。

**接続すると、常に利用可能な送信者が作成されます。**アカウントを接続したとき、それを参照する送信者がない場合、Zavu はアカウント名（WhatsApp の認証済み名称、ページ名、@username）を付けた送信者を自動的に作成します。プロジェクトで最初に作成された送信者がデフォルトになります。パートナー招待による接続では以前からこの方法が採用されており、現在はすべての接続方法で同じように動作します。

送信元の送信者を確認する

GET /v1/senders は、「何を使って、どこから送信できますか？」という問いへの答えです。各送信者の channels 配列が、実際の設定に基づいて算出される機能の信頼できる情報源です。推測によるものではありません。

{
  "id": "sender_12345",
  "name": "Acme Store",
  "channels": ["whatsapp", "sms", "voice"],
  "isDefault": true
}

• channels 配列が空の場合、その送信者はまだ何も送信できません（電話番号だけでは SMS は有効になりません）。
• channels に含まれるのは、接続済みで有効化済みのものだけです。オフになっている接続済みアカウントは、送信が拒否されるため含まれません。
• 電話番号がない送信者には phoneNumber がありません。メール専用の送信者や、enableSmsOneway のみを指定して作成された送信者が該当します。すべての送信者に電話番号があるとは限りません。
• プロジェクトのデフォルト送信者を使用するには、Zavu-Sender を省略します。
• 特定の送信者を指定するには、送信パラメーターオブジェクト内のヘッダーとして、その ID を渡します。'Zavu-Sender': "sender_12345"。

接続済みチャネルを有効化する

プランに含まれている新規接続の WhatsApp アカウント、Telegram ボット、Instagram アカウント、Messenger ページ、またはメールアドレスは、メッセージを送信できる状態になると自動的に有効になります。料金が発生する接続は無効の状態で開始され、有効化するまでその接続での送信は拒否されます。有効化によって接続料金が発生するためです（「制約」を参照）。どちらに該当するかは、送信者の channels を確認してください。ダッシュボード（Accounts、Activate）または API から、送信者とチャネルごとに有効化します。

curl -X POST https://api.zavu.dev/v1/senders/sender_12345/channels/telegram/activate \
  -H "Authorization: Bearer $ZAVU_API_KEY"

{
  "sender": { "id": "sender_12345", "channels": ["telegram"] },
  "channel": "telegram",
  "activated": true,
  "chargedCents": 300,
  "monthlyCents": 300
}

• {channel} は whatsapp、telegram、instagram、messenger、email のいずれかです。SMS、片方向 SMS、音声はメッセージごとに課金されるため、有効化するものはありません（400）。
• chargedCents は、この呼び出しで残高から差し引かれた金額です。チャネルがすでに有効な場合、当月分の支払いが済んでいる場合、またはプランに含まれている場合はゼロになります。2 回呼び出しても、二重に課金されることはありません。
• エラー：402 insufficient_balance、403 plan_limit_reached、409 channel_not_connected（送信者にそのチャネルのアカウントがありません）、409 connection_not_ready（接続済みですが、まだメッセージを送信できる状態ではありません）。
• POST /v1/senders/{senderId}/channels/{channel}/deactivate は、アカウントを切断せずにチャネルをオフにします。すでに支払い済みの月額料金は返金されず、その期間中に再度有効化しても無料です。
• ライブ API キーのみ使用できます。

チャネルごとの接続

接続したもの…	送信者…	次を指定して送信
WhatsApp（埋め込み登録または招待）	自動作成され、アカウントが有効になると channels に whatsapp が含まれます	channel: "whatsapp"
Messenger ページ／Instagram アカウント	自動作成され、ページ名／@ユーザー名が付けられます	channel: "messenger" / "instagram"
Telegram ボット	POST /v1/senders/{senderId}/telegram で紐付けます（ボットトークンは @BotFather から取得）	channel: "telegram"
メールのドメイン（検証済み）	送信者の作成／更新時に emailAddress を指定して紐付けます	channel: "email"
まだ何もない（設定なしですぐ開始）	POST /v1/senders または PATCH /v1/senders/{senderId} で enableSmsOneway: true を指定します。電話番号も認証情報も不要で、すぐに有効になります。受信者は返信できません。米国またはカナダの（+1）番号への送信には、sms と同様に、承認済みの 10DLC キャンペーンが必要です	channel: "sms_oneway"
電話番号	送信者にルーティングします（PATCH /v1/phone-numbers/{id} で senderId を指定）。これにより SMS が有効になります。通話には enableVoice を追加します	channel: "sms" / "voice"

1 つの送信者で複数のチャネルを同時に利用できます。これが要点です。1 つの Zavu-Sender で、あらゆるチャネルを利用できます。

制約

• 送信者は 1 つのプロジェクトに属します。アカウントは最大 1 つの送信者にルーティングされます。
• Webhook は送信者ごとに設定され、その送信者が利用するすべてのチャネルに適用されます。
• AI エージェントは送信者ごとに紐付けられますが、そのエージェント自身の triggerOnChannels に指定されたチャネルにのみ応答します。送信者が受信するチャネルがそのリストに含まれていない場合、エージェントが確認する前に破棄されます。返信もエラーもなく、フィルターを迂回するため Playground では引き続き応答します。破棄の記録は残ります。GET /v1/senders/{senderId}/agent/executions を実行すると、status: "filtered" と errorMessage 内のチャネル名が返されます。特定のチャネルを意図的に除外するのでなければ、["*"] を使用してください。
• 無料プランには 2 つの接続枠が含まれます（そのうち 1 つは WhatsApp アカウントに使用できます）。有料プランでは、接続ごとに月額料金を支払って接続を追加できます。送信者の作成に費用はかかりません。