imessage-management

iMessage の管理（Nexor 経由）

iMessage は Dial を通じて提供される有料の追加チャネルです。専用の青い吹き出しの iMessage 番号が用意され、クライアントの既存の Stripe サブスクリプションに継続課金の回線として追加されます。窓口は Nexor のみです。顧客が Apple や Dial を直接操作することはありません。すべてのツールは API キーから自動的にテナントの範囲に限定されます。client_id は決して受け取ったり渡したりしないでください。

料金 — 定額です。 iMessage 番号は、1 番号あたり月額 350 ドルの定額です。iMessage の料金について話すときは、必ずこの金額を明確に伝えてください。また、現在、定額課金なのは Nexor のチャネルのうち iMessage だけであり、ほかのすべてのチャネル（WhatsApp、SMS、音声、メール）は従量課金であるため、iMessage では利用量にかかわらず毎月同額を支払うことも伝えてください。初月分は購入日に全額が請求され、日割り計算はされません。次の請求サイクルからは、月額 350 ドルがクライアントの月次請求に加算されます。請求する前に、get_imessage_offer で正確な金額と本日請求される金額を必ず確認してください（このツールが正しい情報源です。テスト環境では sandbox: true と dueTodayUsd: 0 が返されます）。

iMessage には独自の番号在庫があり、WhatsApp とまったく同じようにワークフロー（エージェント）に紐付けられます。グループ共有にも対応しており、あるエージェントに紐付けられた番号は、同じエージェントグループ（master_workflow_id）のすべてのエージェントが使用します。Phone／音声／SMS の回線とは別のものです。

よくある間違いを防ぐ唯一のルール

**iMessage の状態を list_phone_numbers から読み取らないでください。**このツールが一覧表示するのは、音声／SMS（Retell）の在庫です。Dial の iMessage 番号が workflow_id: null の音声／SMS 形式の行として表示されることがありますが、**その行は iMessage の状態を表すものではなく、その番号が青い吹き出しの送信元として使用可能かつ割り当て済みかどうかもわかりません。**必ず list_imessage_numbers を使用してください。電話番号の在庫から iMessage の使用準備ができているか推測しそうになったら、そこで中断して、代わりに list_imessage_numbers を呼び出してください。

用途別のツール

用途	ツール
iMessage 番号、状態、各番号を所有するエージェントの確認	list_imessage_numbers
追加オファー（料金、本日請求額、利用資格、カード）の確認	get_imessage_offer
iMessage 番号の購入とプロビジョニング（課金が発生します）	provision_imessage_number
エージェントへの番号の割り当て／割り当て解除	assign_imessage_to_workflow
1 つの番号の現在の詳細（状態、エージェント、名前、写真）の確認	get_imessage_number
青い吹き出しに表示される、リード向けの姓名の設定	set_imessage_display_name
リードに表示されるプロフィール写真の設定	set_imessage_profile_photo
リードへの iMessage の送信	send_message（チャネル imessage）

機能モデル — 「準備完了」だけでは不十分です。割り当ても必要です

iMessage 番号からリードにメッセージを送信できるのは、次の両方を満たす場合だけです。

1. setupStatus が "ready" である（Dial によるプロビジョニングが完了しており、provisioning や failed ではない）。
2. 対象のワークフロー、または同じエージェントグループ内の兄弟エージェントに割り当てられている（assign_imessage_to_workflow で紐付けます。WhatsApp とまったく同じように、兄弟エージェントは master_workflow_id を通じて番号を継承します）。

未割り当ての番号は休止状態です。所有され課金されているものの、どこにも紐付いていないため、何も送信できず、エージェントにも iMessage 機能が表示されません。これが最もよくある落とし穴です。完全に「準備完了」の番号でも、割り当てられていなければ、誰にも連絡できない状態がそのまま続きます。顧客から「iMessage が使えない」と言われたら、ほかを調べる前に list_imessage_numbers で setupStatus: ready と、紐付け先のワークフローが null でないことの両方を確認してください。

list_imessage_numbers／get_imessage_number では、共有状況も直接確認できます。imessageWorkflowId は単独の所有者を示し、owner にはその名前とエージェントグループ（masterWorkflowId、masterName）が含まれます。また、sharedWith には、その番号で送受信している兄弟エージェントがすべて一覧表示されます。sharedWith に含まれるエージェントは接続済みです。別の割り当て呼び出しで「修正」しないでください。所有者が移動するだけです。

電話番号の購入とプロビジョニング（注文、同意が必要 — 料金が発生します）

毎回、次の順序に従ってください。オファーや確認を省略しないでください。

1. get_imessage_offer — 継続的に発生する月額料金（USD）、本日請求される金額 （dueTodayUsd、初月分全額）、canPurchase、購入できない場合はその理由（no_subscription / trial_not_allowed / no_payment_method / external_billing / purchase_disabled）、登録済みのカード （ブランド名 + 下4桁）、現在所有している iMessage 番号の数、および state（ active | purchasable | unavailable）。state が "unavailable" の場合、このアドオンは このクライアントでは有効になっていません（パイロット提供中） — プロビジョニングを試みず、その旨を伝えてください。
2. 定額の月額料金（オファーで確認した番号1つあたり月額350ドル）と初月分全額が本日請求されることをユーザーに伝え、明示的な確認を得ます。 定額であること、つまり送信する iMessage の数にかかわらず毎月同じ料金であることを伝えてください。また、必要であれば、Nexor のチャネルでこの料金体系が適用されるのはこれだけであることも伝えます。明示的な確認なしに請求してはいけません。
3. provision_imessage_number（accept_charge: true を指定） — カードに即時請求し、プロビジョニングを開始します。accept_charge が true でない場合は imessage_consent_required で失敗します。また、クライアントに請求できない場合は、利用資格コード（imessage_no_subscription、imessage_no_payment_method、imessage_purchase_disabled）で失敗します。請求は呼び出しごとに冪等です。同じツール呼び出しを再試行しても安全ですが、意図的にもう一度呼び出すと2つ目の番号を購入します。
4. 新しい番号の setupStatus が "ready" になるまで list_imessage_numbers をポーリングします （プロビジョニングは非同期です。短い間隔で連続して実行せず、間隔を空けて数回ポーリングしてください）。
5. assign_imessage_to_workflow — 担当させるエージェントに番号を割り当てます（以下を参照）。

割り当て／割り当て解除

assign_imessage_to_workflow は iMessage 番号をワークフロー（エージェント）に紐付けます。これにより、そのエージェントが受信 iMessage を受け取れるようになり、番号の表示名にはエージェントのペルソナが反映されます。workflow_id を省略すると紐付けが解除されます（番号は引き続き所有され、課金されますが、紐付けは解除されます）。エージェントグループ（または単独のエージェント）が保持できる iMessage 番号は最大1つです。すでに番号が割り当てられているグループのエージェントに番号を割り当てると、既存の番号は置き換えられ、同じグループの別のエージェントが保持する番号は休止状態になります。グループごとに一度だけ割り当ててください。同じ master_workflow_id の配下にあるすべてのエージェントは、担当エージェントの番号を自動的に使用します。その番号に新しく届いたリードは担当エージェントに割り当てられ、既存のリードはアクティブな実行を保持しているエージェントに割り当てられます。エージェントを選ぶには list_workflows で候補を一覧表示してください。対象がこのクライアントに属していることを確認するには、その対象が一覧に表示されている必要があります。

表示名 — リードに見える名前と写真

すべての iMessage 番号には表示情報があります。姓、名、プロフィール写真で構成され、リードの「メッセージ」アプリでメッセージの横に表示されます。これはダッシュボードの「iMessage 番号を編集」ダイアログと同じ画面で、番号について編集できるのはこれだけです。通話ごとの Dial 設定（着信時の案内、言語、音声、通話時間）と内部ニックネームは、方針によりどこからも編集できません。

• まず get_imessage_number({ number_id }) で読み取ります。Dial から取得した現在の firstName、lastName、avatarUrl に加え、ステータスと紐づくエージェントが返されます。
• 名前：set_imessage_display_name({ number_id, first_name?, last_name? }) — 2 つのうち少なくとも 1 つが必要です。それぞれ 30 文字以下で、空文字列を指定するとその項目がクリアされます。
• 写真：set_imessage_profile_photo({ number_id, image_url }) — 公開されている http(s) 画像 URL（jpeg/png/gif/webp、5 MB 以下）を指定します。写真は差し替えできますが、削除はできません。削除できるとは案内しないでください。このツールでファイルをアップロードすることはできません。画像は事前にホストされている必要があります。オペレーターがファイルしか持っていない場合は、ダッシュボードの iMessage ID 編集画面を案内してください。そこからアップロードできます。
• 同じ回線の WhatsApp：get_imessage_number で whatsappStatus: "ready" と表示される場合、その回線では WhatsApp も利用され、同じ表示情報が共有されます。名前や写真を更新すると、WhatsApp のプロフィールにも反映されます（現在の表示内容は whatsappName、whatsappAvatarUrl で確認できます）。この場合、書き込み全体に WhatsApp の制限が適用されます。名前は姓と名をつなげて 1 行で表示され、合計 25 文字までです。写真は192〜640 px の正方形 JPG または PNGである必要があります。WhatsApp で設定できない内容を書き込むと、fieldErrors.whatsappName / fieldErrors.whatsappAvatarUrl が返され、どちらのチャネルにも変更は反映されません。その旨を伝え、短い名前か正方形の写真を依頼してください。
• 優先順位：デフォルトでは、名前はエージェントのペルソナに従い、割り当て時に再同期されます。名前を手動で設定すると、その名前が優先される値となり、再割り当て時も含め、エージェントに従わなくなります。オペレーターから名前が変更された、または変更されなかった理由を尋ねられたら、この点を伝えてください。
• 変更は数分以内に受信者のデバイスに反映されます。422 imessage_number_invalid_fields という応答には、拒否されたフィールドを示す fieldErrors が含まれます。
• get_imessage_number で再度読み取り、反映後の表示情報を報告してください。

送信

チャネルに imessage を指定して send_message を実行すると、リードにプレーンテキストを送信します。テンプレートも承認も 24 時間の時間制限もありません（WhatsApp とは異なります）。配信確認はなく、応答がない場合は「送信済み」とみなされます。開封確認だけが追加の配信状況を示すため、配信確認がないというだけで送信失敗と報告しないでください。送信にはレート制限があります（新規会話の 1 日あたりの上限と、Apple の「未返信」上限）。送信が拒否されるのは通常の結果なので、その旨を伝えてください。エラーとして再試行しないでください。

「iMessage の検索結果が利用できません」

list_imessage_numbers / get_imessage_offer が利用不可を返す場合、または iMessage ツール自体が見つからない場合、API キーに imessage:read / imessage:write スコープがありません（古いキーは iMessage が追加される前に発行されています）。そのことを明確に伝え、オペレーターにキーのスコープを再付与してもらってください。list_phone_numbers から iMessage の状態を推測して補わないでください。

ガードレール

• client_id は決して渡さないでください。テナントはキーから判定されます。
• プロビジョニングには費用がかかります（月ごとの継続課金）。必ず get_imessage_offer で料金を提示し、provision_imessage_number を実行する前に明示的な確認を得てください。
• 準備が整った番号を実際に利用可能にするには、割り当てが必要です。必ず最後に assign_imessage_to_workflow を実行し、どのエージェントがどの番号を所有しているか、また、どの兄弟エージェントと番号を共有しているかを読み上げてください（owner と sharedWith）。エージェントグループごとに番号は1つです。すでに sharedWith に含まれている兄弟エージェントに、共有番号を再割り当てしてはいけません。
• アイデンティティの編集は名前と写真のみです。通話設定やニックネームは変更しないでください。
• iMessage の状態は必ず list_imessage_numbers から読み取り、list_phone_numbers からは読み取らないでください。

関連スキル

• automation-architecture — エージェントのワークフロー、ステータス、実行間隔、チャネル構成を設定します。iMessage は、ほかのチャネルと同様に、初回連絡のカスケードとブロックごとの実行間隔に組み込まれます。
• whatsapp-management — 並行して利用するメッセージングチャネルです。「エージェントに番号を割り当て、エージェントグループ全体で共有する」という構成は同じですが、iMessage にはないテンプレートと24時間の時間枠を WhatsApp では使用します。