チャネルマネージャAPIを使用したRCSブランドおよびエージェントビルダー

VonageのRCSサービスを利用するには、ブランドはブランドレベルのメタデータを登録し、RCS内でそのブランドを代表する「エージェント」を作成してVerifyされた後、RCSメッセージを送信する際にMessages APIでそれを使用する必要があります。Channel Manager APIは、これらのエンティティ（ブランド、エージェント）をプログラムで管理するためのエンドポイントを提供します。

このガイドでは、その手順を説明する：

• どのような前提条件を満たさなければならないか。
• ブランドマネジメントのエンドポイント：何をするのか、どのようなデータが必要なのか。
• エージェント管理のエンドポイント：何をするのか、どのようなデータが必要なのか。
• オンボーディングのワークフロー：ステップ、ステータスの遷移。

前提条件

APIエンドポイントを使い始める前に、以下のことを確認してください：

• Vonage APIアカウントをお持ちです。
• ブランド管理APIおよびエージェント管理APIを呼び出す権限があります。
• 必要なブランドおよび代理店に関するメタデータはすべて収集済みです。ブランドに関するメタデータには、表示名、法人の詳細情報、登録国、企業のウェブサイト、住所が含まれます。代理店に関するメタデータには、ロゴ、バナー画像、プライバシーポリシー、利用規約、連絡先情報が含まれます。
• 対象地域（例：米国）における検証要件を理解している。

主要APIコンポーネント

主体は2つある：

• ブランド：あなたの組織（会社、ブランド・アイデンティティ）を表します。
• エージェント：メッセージを送信する際、ブランドのアイデンティティ（名称、ロゴ、色など）を体現するものです。

ブランド・マネジメントのエンドポイント

これらのエンドポイントは、ブランドエンティティの一覧表示、作成、更新、削除に使用されます。ブランドを作成するには、表示名と、法人名および法人形態、エンティティの種類、登録国、企業のウェブサイト、登録住所を含む法人の詳細情報が必要です。また、米国で登録されているエンティティについては、連邦税IDも必要です。

エージェント管理エンドポイント

これらのエンドポイントは、ブランドの下にAgentを作成するために使用されます。Agentは、ブランドとしてRCSを送信するために必要なものです。

エージェントの更新：PUT 対 PATCH

両方 PUT そして PATCH エージェントを更新することはできますが、その動作は異なります：

• PUT これは完全な置換です。すべてのフィールドを入力する必要があります — basic_info, visual_design, application_settings, representative, carrier_requirementsそして carriers. 入力されていない項目はすべてクリアされます。
• PATCH 指定した各トップレベルフィールドを完全に置き換えます。階層的なマージは行われません。たとえば、次のように送信した場合、 visual_design、そのすべて visual_design オブジェクトが置換される場合 — 変更するフィールドだけでなく、保持したいすべてのサブフィールドを含めてください。

メディアアセットのアップロード

そのエージェントの visual_design フィールド logo_image そして banner_image 一般に公開されているURLを受け付けます。すでにCDNや公開サーバーで画像をホストしている場合は、それらのURLを直接指定することができます。

Vonage経由でファイルをホストしたい場合は、メディアアップロードエンドポイントを使用してください：

POST https://api.nexmo.com/v1/channel-manager/rcs/media?type={logo|banner}
Content-Type: multipart/form-data

file: <binary file>

このレスポンスは、以下で使用するURLを返します。 visual_design:

{ "public_url": "https://..." }

返されたURLを、以下の値として使用してください。 visual_design.logo_image または visual_design.banner_image エージェントの作成または更新リクエストにおいて。

注釈

• について type クエリパラメータは必須です： logo または banner.
• 対応形式：PNG、JPEG。
• サイズ制限：ロゴは約50 KB、バナーは約200 KBです。制限を超えるファイルは返送されます。 413 Payload Too Large.
• このエンドポイントは、以下のURLで利用可能です。 /v1/ また、v1およびv2の両方のエージェントワークフローで共有されています。

オンボーディングのワークフロー

事前に準備できる情報の量に応じて、一般的なオンボーディングの手法には2つのアプローチがあります。

ワークフロー 1：クイック起動 — すべての情報が準備済み

必要な情報（以下を含む）がすべて揃っている場合は、このワークフローを使用してください。 carrier_requirements （v2および代表的な詳細情報）が事前に確認でき、エージェントをできるだけ早く稼働させたい場合。

1. ブランドの創造

でブランドを作ることから始める。 POST /v2/channel-manager/rcs/brands エンドポイント。以下を指定してください。 display_name そして details 組織の正式名称および組織形態、法人種別、登録国、事業用ウェブサイト、および登録住所を含むオブジェクト。以下を含めること： federal_tax_id 米国で登録されている事業体については、 stock_symbol その組織が上場企業である場合。ブランドが作成されると、APIは id それを brand_id その後の手順で。

リクエスト本文の例：

{
  "display_name": "Acme Bank",
  "details": {
    "organization_name": "Acme Corporation",
    "legal_form": "Limited liability company (LLC)",
    "legal_entity_type": "Private",
    "country_of_registration": "DE",
    "business_website_url": "https://www.example.com",
    "address_line1": "One Main Street",
    "city": "Berlin",
    "state_or_province": "Berlin",
    "zip_or_post_code": "10115"
  }
}

2. エージェントの作成

以下を呼び出してエージェントを作成します。 POST /v2/channel-manager/rcs/agents. すべての項目を最初から入力してください： basic_info, visual_design, application_settings, representative, carrier_requirementsそして carriers.

について basic_info オブジェクトには、以下のフィールドが必要です：

v2 形式を使用してください。 carrier_requirements, これには consent_management そして engagement_flows. v1 形式は非推奨となっています。

には、少なくとも1つのキャリアを指定する必要があります。 carriers 配列である。

リクエスト本文の例：

{
  "basic_info": {
    "display_name": "Acme Bank",
    "sender_id": "acme-bank",
    "brand_id": "0198ecd4-da21-7f8b-91d8-ccfbaec485a7",
    "hosting_region": "EUROPE",
    "agent_purpose": "TRANSACTIONAL",
    "billing_category": "SINGLE_MESSAGE"
  },
  "visual_design": {
    "tagline": "Your trusted banking assistant",
    "brand_color": "#FF5733",
    "logo_image": "https://cdn.example.com/logo.png",
    "banner_image": "https://cdn.example.com/banner.png",
    "phone": [],
    "email": [],
    "website": []
  },
  "application_settings": { "application_id": "a1b2c3d4-..." },
  "representative": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com"
  },
  "carrier_requirements": {
    "version": "v2",
    "agent_preview": {
      "agent_access_instructions": "Visit https://example.com/rcs-agent ...",
      "urls": [{ "media_type": "image", "url": "https://cdn.example.com/preview.png" }]
    },
    "consent_management": {
      "user_messaging_consent_methods": { "selection": ["BY_CREATING_ACCOUNT"] },
      "users_opt_in_process": { "selection": ["WEBSITE_URL"], "links": ["https://www.example.com/subscribe"] },
      "first_opt_in_message": "Welcome! You have opted in to receive updates from Acme Bank.",
      "users_opt_out_methods": { "selection": ["BY_STOP_OR_UNSUBSCRIBE_MESSAGE"] },
      "opt_out_processing_time": { "selection": "WITHIN_5_MINUTES" },
      "opt_out_confirmation_message": { "selection": "SUCCESSFULLY_UNSUBSCRIBED" }
    },
    "engagement_flows": {
      "agent_description": "Acme Bank RCS agent for transactional alerts.",
      "reasons_messages_sent": { "selection": ["ORDER_CONFIRMATION", "PAYMENT_REMINDERS"] },
      "monthly_user_message_count": "THREE_FIVE_MESSAGES",
      "rcs_user_interaction_types": { "selection": ["SIMPLE_REPLIES"] }
    }
  },
  "carriers": ["orange-spain", "vodafone-france"]
}

APIは次のような応答を返します。 agent_id そして、初期状態は DRAFT. エージェントは次の状態に移行する CREATED 約3～5分以内に完了し、その後、テスト対象のデバイスを追加できるようになります。

3. Numbersの追加

以下の方法を使用してテスト番号を追加します POST /v2/channel-manager/rcs/agents/:agent_id/test-devices. これらの Numbers を利用することで、エージェントの体験を本番運用前にテストすることができます。

{
  "phone": "+14155552671"
}

この応答は、 AgentTester オブジェクトを id, phoneそして status. キャリアとの連携が完全に自動化されている場合、通常、2～3分以内に端末の準備が整います。手動での処理が必要なキャリアの場合は、さらに時間がかかる場合があります。

登録済みのすべてのテストデバイスの準備状況を確認するには、いつでも以下のコマンドを使用してください：

GET /v2/channel-manager/rcs/agents/:agent_id/test-devices

リターン 403 デバイスがRCSに対応していない場合、または 503 エージェントがまだ設定されていない場合。

4. テストメッセージを送信する

RCS Agent Builder の UI からテストメッセージを送信し、テスト対象のデバイスでのエージェントの動作を確認してください。この機能は現在、API からは利用できません。

5. エージェントを起動用に送信

以下のコマンドを使用して、エージェントを起動用に送信します。 POST /v2/channel-manager/rcs/agents/:agent_id/launch.

• リターン 202 Accepted 投稿が受理されたとき。
• リターン 422 エージェントが起動可能な状態でない場合。
• エージェントは次のように遷移します PENDING 受理されると、各キャリアは承認手続きを開始します。
• LAUNCHED ステータスは、各航空会社の承認に基づき、航空会社ごとに付与されます。代理店は、 LAUNCHED 一部の通信事業者では、依然として PENDING 他の人に対して。

承認されても、そのエージェントはすぐに本番環境で利用可能になるわけではありません。公開を完了するには、Vonageの運用チームによる内部審査が必要です。このプロセスには通常4～8週間かかりますが、完了後はMessages APIにおいて、そのエージェントを送信者として使用できるようになります。

6. 必要に応じてキャリアを追加する

エージェント作成後は、いつでもキャリアの対応範囲を拡大できます：

POST /v2/channel-manager/rcs/agents/:agent_id/carriers

{
  "carriers": ["dt-germany", "tmobile-us"]
}

リターン 202 Accepted. 返品 409 そのエージェントにすでにキャリアが追加されている場合。

ワークフロー 2：反復型 — まずビジュアルデザインをテストする

通信事業者の要件を完全に確定する前に、エージェントのビジュアルデザインを繰り返し調整したい場合は、このワークフローを使用してください。最小限のパラメータでエージェントを作成し、実機でデザインをテストして、必要に応じて更新した後、残りの項目を入力してリリース申請を行ってください。

1. ブランドの詳細情報を作成または更新する

ワークフロー 1 の手順 1 に従ってください。ブランドには、以下の条件が満たされている必要があります。 details エージェントを起動する前に、このフィールドに入力する必要があります。

2. 最小限のパラメータでエージェントを作成する

以下の内容のみでエージェントを作成します basic_info, visual_design, application_settingsそして carriers.その carrier_requirements そして representative フィールドは作成時に必須ではなく、後から追加することも可能です。

{
  "basic_info": {
    "display_name": "Acme Bank",
    "sender_id": "acme-bank",
    "brand_id": "0198ecd4-da21-7f8b-91d8-ccfbaec485a7",
    "hosting_region": "EUROPE",
    "agent_purpose": "TRANSACTIONAL",
    "billing_category": "SINGLE_MESSAGE"
  },
  "visual_design": {
    "tagline": "Your trusted banking assistant",
    "brand_color": "#FF5733",
    "phone": [],
    "email": [],
    "website": []
  },
  "application_settings": { "application_id": "a1b2c3d4-..." },
  "carriers": ["orange-spain"]
}

エージェントは agent_id 州とともに DRAFT, 次のように移行して CREATED 約3～5分後。

3. テスト用デバイスを追加する

POST /v2/channel-manager/rcs/agents/:agent_id/test-devices

{
  "phone": "+34613994828"
}

4. テストメッセージを送信する

RCS Agent BuilderのUIからテストメッセージを送信し、エージェントのビジュアルデザインが実際のデバイス上でどのように表示されるかを確認してください。

5. 必要に応じてビジュアルデザインを更新する

変更が必要な場合は、エージェントを部分的に更新してください：

PATCH /v2/channel-manager/rcs/agents/:agent_id

{
  "visual_design": {
    "tagline": "Updated tagline",
    "brand_color": "#0033CC",
    "phone": [],
    "email": [],
    "website": []
  }
}

完全自動化された運送会社との連携の場合、変更は通常2～3分以内に反映されます。手動での処理が必要な運送会社の場合は、さらに時間がかかる場合があります。

デザインが完成するまで、手順4～5を繰り返してください。

6. すべての項目を入力し、公開の準備を整える

デザインが完成するまで、手順4～5を繰り返します。

6. すべての項目を入力し、公開の準備を整える

デザインが確定したら、次の手順に従ってください。 PUT 残りのすべての項目を入力するには：

{
  "basic_info": { "..." : "..." },
  "visual_design": { "..." : "..." },
  "application_settings": { "application_id": "a1b2c3d4-..." },
  "representative": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com"
  },
  "carrier_requirements": {
    "version": "v2",
    "agent_preview": { "..." : "..." },
    "consent_management": { "..." : "..." },
    "engagement_flows": { "..." : "..." }
  },
  "carriers": ["orange-spain", "vodafone-france"]
}

7. エージェントを起動用に送信

POST /v2/channel-manager/rcs/agents/:agent_id/launch

起動時の動作や状態遷移の詳細については、ワークフロー1の手順5を参照してください。

8. 必要に応じてキャリアを追加する

POST /v2/channel-manager/rcs/agents/:agent_id/carriers

{
  "carriers": ["dt-germany"]
}

継続的メンテナンス

メタデータ（ロゴや説明文など）の更新が必要な場合は、検証後に編集可能なフィールドを確認するか、Accountマネージャーにお問い合わせください。一部のフィールドはロックされている場合があります。

エージェントのステータス

さらに読む

RCSエージェントビルダーガイド
チャネルマネージャAPIリファレンス