sent-contacts

送信済み連絡先

contacts.list、contacts.get、contacts.create_many、contacts.delete、contacts.message_summaryを使って連絡先を操作します。

接続とスコープの確認

クライアント管理のOAuth 2.1/PKCEを使用します。トークン、APIキー、認可ヘッダー、クライアントID、シークレットを要求または公開してはいけません。変更を行う前に、接続コンテキストから有効な組織と送信者プロファイルを提示します。どちらかを確認できない場合は、sent-account-readinessを使って認可済みのスコープを調べます。

電話番号は可能な限りマスキングします。タスクに必要な連絡先フィールドだけを返し、確認後に連絡先データを繰り返し表示しないでください。番号の存在やメッセージ履歴があることは、同意がある証拠にはなりません。

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

連絡先の読み取り

• contacts.listを使って連絡先を検索したり、ページ単位で取得したりします。利用可能な中で最も範囲の狭いフィルターを適用し、必要もなく連絡先一覧全体を出力しないでください。
• 正確な連絡先識別子が分かっている場合や、削除の前にはcontacts.getを使います。
• 連絡先のメッセージ概要にはcontacts.message_summaryを使います。概要データと、同意の証明や現在の到達可能性は区別してください。

読み取り専用の呼び出しには、変更の確認は不要です。

連絡先の一括作成

1. 提案されたレコードをローカルで検証し、重複を除去します。ユーザーが実際に指定したフィールドだけを保持します。
2. ツールを呼び出さずに、contacts.create_manyの正確な引数を組み立てます。
3. 選択した組織、送信者プロファイル、レコード数、重複の処理方法、各正確な対象を含むペイロードのプレビューを表示します。実行者が確認できる範囲で電話番号をマスキングします。正確な確認に必要な場合に限り、完全な値を一度だけ表示します。
4. この正確な一括処理に対する明示的な確認を求めます。以前の承認や一般的な承認では不十分です。
5. 確認後、直ちにcontacts.create_manyを呼び出します。レコードまたはスコープに変更があれば、確認は無効になります。

直前にプレビューを表示して明示的な確認を得ていない限り、contacts.create_manyを呼び出してはいけません。再試行もすべて新たな変更として扱い、その都度、新しいプレビューと明示的な確認を得てください。

連絡先の削除

1. 要求された連絡先を、曖昧さのない単一の識別子に特定します。
2. 削除の前に、contacts.getで正確な対象を取得します。推測した識別子、広範なフィルター、古い一覧の結果を使って削除してはいけません。
3. 選択した組織、送信者プロファイル、正確な連絡先識別子、表示名、マスキングしたアドレスを含む削除プレビューを表示します。削除が取り消せない操作であることを明示します。
4. その正確な対象を削除するための明示的な確認を求めます。
5. 確認後、直ちにcontacts.deleteを呼び出します。対象、スコープ、レコードに変更があった場合は、再取得してプレビューをやり直します。

対象を取得し、直前に明示的な確認を得ていない限り、contacts.deleteを呼び出してはいけません。再試行するたびに、再取得、新しいプレビュー、新たな明示的な確認が必要です。

結果の報告

連絡先レコード全体ではなく、件数と変更されない識別子を報告します。作成または削除の結果が曖昧な場合、成功したと決めつけたり、自動的に再試行したりしてはいけません。可能な場合は対象を再読み込みし、不確実な点を説明したうえで、追加の変更を行う前に新たな確認を得てください。