API以上のRCS

RCS API、Messages API、または Conversations API を使用して RCS メッセージとイベントを送受信します。RCS API は、チャネル固有の統合のための完全な RCS 機能セットを公開します。Messages API と Conversations API は、オムニチャネルのユースケースで他のチャネルとともに RCS をサポートしています。

開始する前に、compliance and guidelines と message types についてよく理解してください。

RCS APIでできること

RCS API を使用して、次のことを行います。

• オプションの SMS または MMS フェイルオーバー、有効期間、スケジュール配信、配信時間枠、URL クリック追跡を使用して、テキスト、ファイル、カード、カルーセル、テンプレート形式でリッチな送信メッセージを送信します。
• 入力インジケーターや開封確認などのメッセージングイベントを送信します。
• 受信メッセージとリアルタイムイベント(ユーザーアクションと入力)を受信します。
• Webhook を介してメッセージ配信、既読状態、会話セッションの開始を追跡します。
• 送信前に、RCS の宛先番号の機能を確認してください。
• 送信者、テスト番号、メッセージテンプレートをプログラムで管理します。

この API は、トランザクション アラート、OTP、プロモーション メッセージから、豊富な双方向の会話エクスペリエンスまで、フルサイクルの通信をサポートします。

認証と構成のセットアップ

RCS メッセージの送受信を開始する前に、次の設定を完了してください。

• ** API認証ガイドを使用して統合を認証**します。すべての RCS エンドポイントは、標準の NTT CPaaS の「権限付与: アプリ」ヘッダーを使用して、パーソナライズされたベース URL で利用できます。
• 送信メッセージを送信する前に、RCS 送信者を作成して起動します。送信者の作成と起動の手順については、RCSを参照してください。
• Webhook 通知を構成して、配信レポート、表示されたレポート、受信メッセージ、およびイベントを受信します。サブスクリプション管理APIからサブスクリプションを設定するか、 NTT CPaaSのWebインターフェースでグローバルWebhook URLを割り当てます。
• プロモーション コンテンツを送信する前に、地域の規制要件とオプトイン要件を満たすために compliance and guidelines を確認してください。

送信メッセージ

送信メッセージは、モバイル終端(MT)メッセージとも呼ばれ、RCSを介してビジネスからエンドユーザーに送信されるメッセージです。RCS は、テキスト、ファイル、カード、カルーセル、テンプレート メッセージなど、複数のメッセージ形式をサポートしており、それぞれがリッチでインタラクティブなコミュニケーションを可能にします。詳細な形式仕様、サポートされているメディアの種類、および構造要件については、「 message types」を参照してください。

一括およびテンプレート バリアントを含む送信エンドポイントの完全なリストについては、RCS API リファレンスの「 アウトバウンド メッセージ 」を参照してください。

アウトバウンド イベント

RCS は、メッセージ交換中にリアルタイムのフィードバックを提供する会話インジケーターをサポートしています。iOSとAndroidの両方のプラットフォームは、追加費用なしでこれらの指標をサポートしています。

入力インジケーターは、送信者エージェントまたはチャットボットが積極的に応答を作成していることをエンドユーザーに通知します。インジケーターは、エンド ユーザー デバイスに 5 秒間表示されます。

開封確認 送信者エージェントがエンドユーザーからのメッセージを閲覧したことを確認します。エンドユーザーデバイスには、メッセージが表示されたことを示すインジケーターが表示されます。

エンドポイントの詳細については、RCS API リファレンスの「 アウトバウンド イベント 」を参照してください。

受信メッセージ

受信メッセージは、モバイル発信(MO)メッセージとも呼ばれ、エンド ユーザーから RCS を介してビジネスに送信されるメッセージです。受信メッセージは双方向通信を可能にし、テキスト、ファイル、位置データ、提案応答を含めることができます。インバウンドメッセージは、Webhook通知を介してリアルタイムでシステムに配信されます。受信メッセージの種類の詳細については、「メッセージの種類」を参照してください。

Webhook の詳細については、RCS API リファレンスの「 受信メッセージ 」を参照してください。

インバウンドイベント

エンド ユーザーが提案されたアクションを操作したり、入力を開始したりしたときに Webhook 通知を受け取ります。

Webhook の詳細については、RCS API リファレンスの「 受信イベント 」を参照してください。

ログとステータスレポート

RCS メッセージ配信とエンド ユーザー エンゲージメントは、配信レポート、表示レポート、および詳細なメッセージ ログを通じて監視できます。配信レポートでは、メッセージがエンド ユーザー デバイスに届いたことが確認されます。表示されたレポートは、エンドユーザーがメッセージを開いて表示したことを示します。

Webhook での請求の透明性

RCS Webhook には、各メッセージに適用される請求タイプを可視化する請求の透明性フィールドが含まれています。これらのフィールドは、メッセージが非会話型請求から会話型請求に移行したタイミングを追跡するのに役立ちます。

これらのフィールドは、配信レポート (DLR) Webhook、モバイル発信元 (MO) メッセージ Webhook、およびイベント Webhook に表示されます。

会話開始 Webhook イベント

専用の Webhook イベントは、24 時間の会話型課金セッションが開始されるとリアルタイムで通知します。このイベントは、A2P (ビジネス開始) と P2A (ユーザー開始) の両方の会話セッションでトリガーされます。

イベントは、次の各シナリオでトリガーされます。

• A2P会話: エンドユーザーが24時間以内にビジネスメッセージに返信し、会話セッションを作成します。
• P2A 会話: 企業が 24 時間以内に未承諾のエンド ユーザー メッセージに応答し、会話セッションを作成します。

会話開始イベントは、会話またはセッションが確立されると、元の適格会話メッセージを遡及的に更新します。グローバル会話型課金モデルでは、A2P または P2A 会話に切り替わったメッセージが更新されます。米国では、セッション・トリガーが満たされると、対話式セッションの一部となった修飾メッセージを更新します。

エンドポイントと Webhook の詳細 (配信レポート、メッセージ ログ、表示されたレポート、会話開始イベント) については、RCS API リファレンスの「 ログと状態レポート 」を参照してください。

機能チェック

メッセージを送信する前に、特定の電話番号の RCS が利用可能であることを確認します。機能チェックを使用して、RCS が使用できない場合に SMS へのフォールバック ロジックを実装します。同期と非同期 (Webhook) の両方の機能チェックがサポートされています。

エンドポイントと Webhook の詳細については、RCS API リファレンスの「 機能チェック 」を参照してください。

送信者管理

RCS 送信者、その構成、および起動要求を管理します。送信者管理には、送信者の作成、構成とプラットフォーム パラメーターの更新、起動ステータスの追跡、状態変更に関する Webhook 通知の受信が含まれます。また、特定の国でのローンチのリクエスト、必要なすべての情報を含むローンチリクエストの送信、RCS ローンチが利用可能なプロバイダーおよび国ごとのローンチ要件の表示についても説明します。

1 つの国のローンチをリクエストする場合は、特定のプロバイダーを選択できます。複数の国を選択した場合、プロバイダーの選択は利用できません。

次のシナリオでは、送信者の再起動を要求できます。

• プロバイダーが最初の起動要求を拒否しました。
• プロバイダーが元の起動要求から除外されました。
• 追加のプロバイダーは、送信者がすでに起動されている国で利用可能になりました。

追加のプロバイダーが利用可能になると、送信者の状態は 起動 - 部分的な成功 に変わります。その後、別の送信者を作成せずに、追加のプロバイダーの起動リクエストを送信できます。Webhook 通知をサブスクライブして、プロバイダーの可用性と送信者ステータスの変更に関する最新情報を受け取ります。

送信者管理 API を使用して、次のことを行います。

• 起動前に送信者を作成して更新します。
• 送信者と送信者の起動ステータスを追跡します。
• 利用可能な RCS プロバイダーを表示します。
• すでに起動されている送信者の追加プロバイダーへの起動を要求します。

リソース要求 API を使用して、次のことを行います。

• 起動情報を照会します。
• 起動要求を送信して更新します。
• 起動要求のライフサイクルを追跡します。
• 起動情報と送信者情報に関するフィードバックを受け取ります。
• 送信リクエストにstructuredFeedbackフラグを含めることで、起動拒否に対する構造化フィードバックをオプトインします。

エンドポイントと Webhook の詳細については、RCS API リファレンスの「 送信者管理 」を参照してください。

送信者の検証と起動の承認

NTT CPaaSは、RCSテクノロジープロバイダーまたはMNO（モバイルネットワーク オペレーター）に送信者の確認を依頼します。一部の MNO では、サービスを使用するために追加のチェックを完了する必要がある場合があります。詳細については、NTT CPaaS アカウント マネージャーまたは サポート にお問い合わせください。

起動要求が拒否された場合、拒否によって、問題があるフィールドとその解決方法が特定されます。構造化されたフィードバックを受け取るには、リソース リクエスト API を介して起動リクエストを送信するときにstructuredFeedbackフラグを含めます。構造化フィードバックでは、自由形式のテキストではなく、フィールドごとのエラーコードが提供されます。詳細については、「構造化された起動フィードバック](#structured-launch-feedback)を参照してください。

ローンチ承認後:

• 送信者は稼働しており、運用トラフィックに対して承認されています。
• RCS メッセージとキャンペーンは、送信者が起動された宛先に制限なく送信できます。
• 連絡先をテスターとして招待したり、番号をセーフリストに登録したりする必要はありません。

送信者管理 Webhook

RCS 送信者管理は、送信者ステータスの変更、プロバイダーの可用性の更新、起動ステータスの更新に関する Webhook 通知を提供します。これらのイベントは、 サブスクリプション管理 API を使用してサブスクライブします。

送信者更新 Webhook

SENDER_UPDATEWebhook は、送信者ステータスが変化したときに通知します。各イベントには、ステータスが変更された理由を説明する「理由」フィールドが含まれています。

送信者ステータスの完全なリストと、各ステータスが送信者編集、テスト デバイス、および本番トラフィックに与える影響については、「送信者ステータス](/rcs/get-started#送信者-statuses)を参照してください。

ペイロードの例

プロバイダーの更新 Webhook

PROVIDER_UPDATEWebhook は、ある国で追加のRCSプロバイダーが利用可能になったときに通知します。これは市場レベルのイベントであり、送信者レベルのイベントではありません。その国で送信者が起動されているかどうかに関係なく、起動されます。

events: ["PROVIDER_UPDATE"] でこのイベントを購読してください。サブスクリプションには送信者リソースは必要ありません。

同じ国で複数のプロバイダーが同時に利用可能になった場合、プロバイダーごとに個別のイベントが送信されます。

ペイロードの例

構造化された起動フィードバック

リソースリクエスト API を使用して起動リクエストを送信する場合は、structuredFeedbackオプトインフラグを含めます。起動リクエストが拒否されると、システムはRCS_SENDER_LAUNCH_STATUS_UPDATEWebhook イベントと GET RCS 送信者起動ステータス API応答を通じてフィードバックを配信します。フィードバックには、自由形式のテキストではなく、構造化されたエラー コードが含まれます。

構造化フィードバックは、次の構造でフィールドごとの拒否理由を提供します。

• externalRequirementKey は、起動データフィールド (optInUrl など) を識別します。
• requirementKey は、送信者データ フィールド (description など) を識別します。
• errors には、それぞれ key、reason、および details を持つ error オブジェクトの配列が含まれています。

feedback 配列は、各プロバイダーのカバレッジエントリの以前の自由形式の rejectionReason フィールドを置き換えます。

構造化フィードバック ペイロード形式については、「 RCS 送信者起動更新イベントの受信 API リファレンス」を参照してください。

テスト番号管理

起動前に RCS の送信者を検証するために使用されるテスト番号を管理します。テスト番号の管理には、テスト番号の追加と削除、プライマリ テスト番号の設定、可用性の更新、テスト番号の状態変更時の Webhook 通知の受信が含まれます。

エンドポイントと Webhook の詳細については、RCS API リファレンスの「 番号管理のテスト 」を参照してください。

テンプレート管理

RCS メッセージ テンプレートを作成、更新し、承認のために送信します。テンプレート管理には、テンプレートのリスト、テンプレートの作成と編集、承認のための送信、承認ステータスの確認、テンプレートの状態変更時の Webhook 通知の受信が含まれます。

エンドポイントと Webhook の詳細については、RCS API リファレンスの「 テンプレート管理 」を参照してください。