sent-messaging

送信メッセージ

messages.send、messages.get、messages.activities.list を使用して、ダイレクトメッセージのワークフローを操作します。

接続とスコープの確認

1. MCP クライアントに OAuth 2.1/PKCE 認可を実行させます。トークン、API キー、認可ヘッダー、クライアント ID、シークレットを要求、受領、表示、保存してはいけません。
2. 変更を加える前に、アクティブな接続で選択されている組織と Sender Profile を表示します。クライアントのコンテキストで両方を確認できない場合は、続行前に sent-account-readiness を使用して認可済みのスコープを確認します。
3. 組織の許可で対応している場合は、明示的に指定して検証済みの代理実行プロファイルを使用します。
4. 機密性の高い出力を最小限に抑えます。可能な場合は電話番号をマスキングし、オペレーターがメッセージ本文を確認した後に再掲してはいけません。

MCP がサポートされていない場合や認可に失敗した場合も、ペイロードの計画にはこのスキルを使用できる状態にしておきます。実行には互換性のあるクライアントまたは再認可が必要であることを説明し、ユーザーに認証情報の貼り付けを求めてはいけません。

組織の許可では、ツールのスキーマにある省略可能な profileId を指定して、所有する Sender Profile を選択できます。認証済みアカウントとして操作する場合は省略します。sender_profiles.list または sender_profiles.get で所有権を検証し、事前確認の読み取り、変更、変更後の読み取りで同じセレクターを使用します。プロファイルの許可ではこのセレクターを使用できません。別の組織または許可範囲外のプロファイルを使うには、再認可してください。存在しないスコープフィールドを作成したり、認証情報を要求したりしてはいけません。

メッセージの確認

• メッセージ識別子がわかっている場合は、現在のレコードを messages.get で取得します。
• ライフサイクルイベントと配信の証拠を確認するには、messages.activities.list を使用します。
• 送信が受理またはキューに追加されたことは、配信の証明ではないと伝えます。返された状態またはアクティビティによって配信が確認できる場合にのみ、配信済みと報告します。
• 質問への回答に必要な識別子、タイムスタンプ、ステータスの証拠を返します。宛先データはマスキングし、必要な場合を除いてメッセージ本文は省略します。

多数の配信レコードを対象とした集計トレンド、ファネル、根本原因分析には、messaging-performance-analyzer に引き継ぎます。

送信の準備

1. 使用するチャネル、Sender Profile、宛先、既存のテンプレート、変数、scheduledAt、idempotencyKey を確認します。送信にはテンプレートのみ使用できます。最初に同じ代理実行スコープで templates.list または templates.get を使用し、template に実際の ID または名前を指定して、宣言されているすべての変数を template.parameters に渡します。メッセージ本文をテンプレート名として渡したり、自由形式のテキスト引数を作成したりしてはいけません。不足している値を補ってはいけません。
2. 大量送信の場合は、変更の準備前に sent-account-readiness を使用して balance.get を確認します。利用可能な残高またはアカウントの準備状況が不十分、あるいは不明確な場合は停止します。
3. ツールを呼び出さずに、正確な messages.send の引数を組み立てます。
4. 選択された組織、Sender Profile、チャネル、正確な送信先、既存テンプレートの識別子と確認済みの内容、変数、スケジュールと冪等性の入力を含むペイロードのプレビューを表示します。機密情報は一度だけ表示し、オペレーターが送信先を確認できる状態を保ったままマスキングします。
5. このペイロードに対する明示的な確認を求めます。会話の前半で得た一般的な承認は不十分です。
6. 確認を得た直後に messages.send を呼び出します。ペイロードの値、スコープ、経過したコンテキストのいずれかに変更があれば、確認を破棄し、プレビューを再度提示します。

直前にプレビューを提示し、明示的な確認を得ることなく messages.send を呼び出してはいけません。

送信を予約する

scheduledAt は省略可能です。ユーザーの日付、時刻、タイムゾーンを、UTC オフセットまたは Z を明示した ISO-8601 タイムスタンプに変換してください。オフセットのないタイムスタンプは拒否されます。実行時点で、指定された日時が1分後から30日後までの範囲内である必要があります。プレビューには正確な現地時刻と UTC の日時を含め、送信を呼び出す前にこの範囲内であることを再確認してください。

受付が成功すると、scheduledAt を含む QUEUED が返されます。その後、メッセージは SCHEDULED に移行し、messages.get で確認できます。指定時刻の前後数分以内に送信されます。受信者のサイレント時間帯によって、次に許可される時刻まで延期されることがあり、その場合は message.scheduled で通知されます。正確な配信時刻を約束しないでください。アカウントの予約送信上限により、送信が拒否されることがあります。MCP には再スケジュールやキャンセルのツールはありません。存在しないツールを作り出さないでください。

スキーマでサポートされている冪等性には、キャメルケースの idempotencyKey を使用してください。同じキーを使うと、キャッシュされた送信結果を24時間再利用できます。同じ操作を復旧するときは、元のキーと引数をそのまま使用してください。別の送信を意図している場合は、専用のキーが必要です。冪等性はレビューや確認の代わりにはなりません。

結果と再試行を処理する

• メッセージ識別子と、返された受付状態を伝えてください。応答から確認できるのがその範囲までなら、「受付済み」または「キューに登録済み」と伝え、「配信済み」とは言わないでください。
• ユーザーがその後の配信状態を尋ねた場合は、messages.get または messages.activities.list を使用してください。
• 再試行は毎回、新しい変更操作として扱ってください。ペイロードを再構築し、新しいプレビューを表示してから、再試行の直前に明示的な確認を改めて得てください。
• 状況が不明な送信を、決して無条件で再試行しないでください。最初の呼び出しがタイムアウトした場合や結果が不明な場合は、識別子があれば messages.get と messages.activities.list を調べてください。確かな証拠が得られなければ、結果が不明であることと重複送信のリスクを伝えてください。運用担当者が再送を選び、新しいプレビューと確認を完了した後に限り、別の送信を試みてください。