RCS Brand and Agent Builder using Channel Manager API

To use Vonage's RCS offering, a brand needs to register some brand‐level metadata, then create an Agent that represents the brand in RCS, get it verified, then use it in the Messages API when sending RCS messages. The Channel Manager API provides endpoints for managing these entities (Brand, Agent) programmatically.

This guide walks you through:

• What prerequisites must be met.
• The Brand Management endpoints: what they do, what data is required.
• The Agent Management endpoints: what they do, what data is required.
• The full onboarding workflow: steps, status transitions.

Prerequisites

Before you start with the API endpoints, ensure:

• You have a Vonage API account.
• You are authorized to call Brand Management and Agent Management APIs.
• You have gathered all required brand and agent metadata. Brand metadata includes the display name, legal organization details, registration country, business website, and address. Agent metadata includes the logo, banner image, privacy policy, terms of service, and contact information.
• You understand the verification requirements in your target territory (e.g. in the U.S.).

Key API Components

There are two main entities:

• Brand: represents your organization (company, brand identity).
• Agent: represents the brand's identity when sending messages (name, logo, color, etc.).

Brand Management Endpoints

These endpoints are used to list, create, update, or delete the Brand entity. Creating a brand requires a display name and legal organization details, including the legal name and form, entity type, country of registration, business website, and registered address. A federal tax ID is also required for entities registered in the United States.

Agent Management Endpoints

These endpoints are used to create Agents under a brand. An Agent is what is required to send RCS as the brand.

Updating agents: PUT vs PATCH

Both PUT and PATCH can update an agent, but they behave differently:

• PUT is a full replacement. You must provide all fields — basic_info, visual_design, application_settings, representative, carrier_requirements, and carriers. Any field omitted is cleared.
• PATCH replaces each top-level field you provide in full. There is no deep merge. For example, if you send visual_design, the entire visual_design object is replaced — include all sub-fields you want to keep, not just the ones you are changing.

Uploading Media Assets

The agent's visual_design fields logo_image and banner_image accept publicly accessible URLs. If you already host your images on a CDN or public server, you can reference those URLs directly.

If you prefer to host the files through Vonage, use the media upload endpoint:

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

file: <binary file>

The response returns the URL to use in visual_design:

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

Use the returned URL as the value for visual_design.logo_image or visual_design.banner_image in your agent creation or update request.

Notes:

• The type query parameter is required: logo or banner.
• Supported formats: PNG, JPEG.
• Size limits: logo ~50 KB, banner ~200 KB. Files exceeding the limit return 413 Payload Too Large.
• This endpoint is available at /v1/ and is shared across both v1 and v2 agent workflows.

Onboarding Workflows

There are two common onboarding approaches depending on how much information you have ready upfront.

Workflow 1: Fast Launch — All Info Ready

Use this workflow when all required information (including carrier_requirements v2 and representative details) is available upfront and you want the agent live as quickly as possible.

1. Create Brand

Begin by creating a brand with the POST /v2/channel-manager/rcs/brands endpoint. Provide a display_name and a details object containing the organization's legal name and form, entity type, country of registration, business website, and registered address. Include federal_tax_id for an entity registered in the United States and stock_symbol when the organization is publicly traded. Once the brand is created, the API returns an id that you use as the brand_id in subsequent steps.

Example request body:

{
  "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. Create Agent

Create an agent by calling POST /v2/channel-manager/rcs/agents. Provide all fields upfront: basic_info, visual_design, application_settings, representative, carrier_requirements, and carriers.

The basic_info object requires the following fields:

Use the v2 format for carrier_requirements, which requires consent_management and engagement_flows. The v1 format is deprecated.

You must provide at least one carrier in the carriers array.

Example request body:

{
  "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"]
}

The API responds with an agent_id and an initial state of DRAFT. The agent transitions to CREATED within approximately 3–5 minutes, after which test devices can be added.

3. Add test numbers

Add test numbers using POST /v2/channel-manager/rcs/agents/:agent_id/test-devices. These numbers allow you to test the agent experience before it goes live.

{
  "phone": "+14155552671"
}

The response returns an AgentTester object with id, phone, and status. For fully automated carrier integrations, the device is typically ready within 2–3 minutes. Carriers that require manual processing may take longer.

To check the readiness status of all registered test devices at any time, use:

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

Returns 403 if the device does not support RCS, or 503 if the agent is not yet set up.

4. Send test messages

Send test messages from the RCS Agent Builder UI to confirm the agent experience on your test devices. This function is currently not available via the API.

5. Submit Agent for Launch

Submit the agent for launch using POST /v2/channel-manager/rcs/agents/:agent_id/launch.

• Returns 202 Accepted when the submission is accepted.
• Returns 422 if the agent is not in a launchable state.
• The agent transitions to PENDING once accepted, and carriers begin the approval process.
• LAUNCHED status is granted per-carrier as each carrier approves. The agent may be LAUNCHED on some carriers while still PENDING on others.

When approved, the agent does not immediately become available in production. An internal review by Vonage's operations team is required to complete the launch. This process typically takes 4–8 weeks, after which you can begin using the agent as the sender in the Messages API.

6. Add more carriers if needed

You can expand carrier coverage at any time after agent creation:

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

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

Returns 202 Accepted. Returns 409 if a carrier was already added to the agent.

Workflow 2: Iterative — Test Visual Design First

Use this workflow when you want to iterate on the agent's visual design before committing to the full carrier requirements. Create the agent with minimum parameters, test the design on a real device, update as needed, and then complete the remaining fields before submitting for launch.

1. Create or update the brand with details

Follow step 1 from Workflow 1. The brand must have the details field populated before the agent can be launched.

2. Create Agent with minimum parameters

Create the agent with only basic_info, visual_design, application_settings, and carriers. The carrier_requirements and representative fields are optional at creation and can be added later.

{
  "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"]
}

The agent returns an agent_id with state DRAFT, transitioning to CREATED in approximately 3–5 minutes.

3. Add a test device

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

{
  "phone": "+34613994828"
}

4. Send a test message

Send a test message via the RCS Agent Builder UI and observe how the agent's visual design renders on the actual device.

5. Update the visual design if needed

If changes are needed, partially update the agent:

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

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

For fully automated carrier integrations, changes are typically live within 2–3 minutes. Carriers requiring manual processing may take longer.

Repeat steps 4–5 until the design is finalised.

6. Complete all fields and prepare for launch

Repeat steps 4–5 until the design is finalized.

6. Complete all fields and prepare for launch

Once the design is finalized, use PUT to provide all remaining fields:

{
  "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. Submit Agent for Launch

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

See step 5 of Workflow 1 for details on launch behavior and state transitions.

8. Add more carriers if needed

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

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

Ongoing Maintenance

If some metadata needs updating (logo, description), check which fields are editable post-verification or contact your Account Manager. Some may be locked.

Agent statuses

Further reading

RCS Agent Builder Guide
Channel Manager API Reference