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/agent metadata: brand name, logo, banner image, website, privacy policy, terms of service, email/display info, etc.
• 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 create or update the Brand entity.

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.

Onboarding Workflow

This is the typical onboarding flow for putting together Brand and Agent endpoints:

1. Create Brand

Begin by creating a brand with the POST /v1/channel-manager/rcs/brands endpoint. In this request, you register your brand name. Once the brand is created, the API returns a brand_id that you must reference in all subsequent steps.

2. Create Agent

When the brand exists, you create an agent by calling the POST /v1/channel-manager/rcs/agents endpoint. The agent represents the customer-facing profile that will deliver RCS messages on behalf of your brand. In this request, you provide the brand_id along with the agent’s display name, description, images, and contact details. The API responds with an agent_id, which becomes the identifier for all operations on the agent.

3. Add test numbers

Add test numbers using the POST https://api.nexmo.com/v1/channel-manager/rcs/agents/:agent_id/test-devices endpoint. These numbers allow you to test the agent experience before it goes live.

4. Launch Agent

Launch the agent using PUT /v1/channel-manager/rcs/agents/:agent_id or using PATCH /v1/channel-manager/rcs/agents/:agent_id and by providing relevant information.

5. Select Carriers

Select the carriers that should host the agent by calling the POST /v1/channel-manager/rcs/agents/{agentId}/carriers endpoint. In this request, you specify the list of carrier IDs where you want the agent to be launched. You can review the carrier configuration with GET /v1/channel-manager/rcs/carriers.

When the carriers and Google approve the agent, this does not immediately make the agent available in production. Instead, it submits the request for an internal review by our operations team, who will work with the carriers to complete the launch. The process typically takes 4–8 weeks, after which you can begin using the agent as the sender in the Messages API to deliver RCS messages to your customers.

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