Build your first agent

An agent is a programmatic entity that interacts with users by sending messages. An agent may provide a simple one-way experience (such as sending an OTP message), or it may be conversational and react to users' responses in a back-and-forth exchange.

Users interact with agents through an RCS-enabled messaging app, such as the Messages app, on their devices. In this example, you'll create a basic RBM agent that can send a simple message to a test device and receive a response.

The flow of a message through an RBM-enabled conversation


Before you get started with your agent, you'll need the following items:

  • Your RBM Google account
  • Your agent's name
  • An Android device with an active phone number
  • A development machine that can run sample code

Set up your test device

To communicate with an unlaunched RBM agent, a test device needs to be RCS-enabled, but not all Android devices can receive RCS messages by default. You can check the RCS status of your device and, if necessary, enable RCS by configuring your device with pre-release versions of the Messages and Carrier Services apps.

Check the RCS status of your device

  1. In the Messages app, tap the button, then tap Settings.
  2. Tap Chat features, and find the Status value.

    If Status is Connected, RCS is active on your device.

Next steps

If RCS is active on your device, you're ready to set up your agent. If RCS is inactive on your device, you need to enable RCS on your device before you can test your RBM agent.

Set up your agent

RBM agents use the RCS Business Messaging (RBM) API to send messages, events, and other requests to users. When you create an agent, you enable access to the RBM API and define your agent's name and region.

Identify the agent's region

The RBM API supports three regional endpoints to help businesses comply with regional and business requirements. RBM agents can exist in one of three regions:

  • North America
  • Europe
  • Asia Pacific

When you create your agent, choose its region based on the applicable regulations, requirements, and proximity to end users. Note that region is not country specific. It identifies the area that your agent operates in. Google uses this information to determine where to store message data and how to route message traffic appropriately.

Identify the agent's use case

Each RBM agent is required to have a predefined use case that reflects the nature of the conversations it is intended to have with end users and to help businesses comply with business rules. RBM supports four use cases:

  • OTP: One-time passwords required to securely authenticate an account or confirm a transaction
  • Transactional: Notifications, updates or alerts to share information directly relevant to a customer's existing services or products, such as alerts for suspicious account activities, purchase confirmations, and shipping notifications.
  • Promotional: Sales, marketing and promotional messages to new or existing customers, with the objective to increase awareness, engagement and sales.
  • Multi-use: Conversational flows that combine transactional and promotional use cases, such as sending an account notification and then offering a discount or upgrade for a new product and service.

See Choose the right use case for a more thorough description of when to use each use case.

Determine the agent's Billing Category

Carriers that approve RBM content on their networks also bill for delivering RBM messages to their subscribers using this billing framework:

  • Conversational - A charge for a conversation that consists of multiple A2P and P2A messages within a given time period.
  • Single Message - A charge for a single message containing rich RBM content (such as a message containing a Rich Card or Carousel).
  • Basic Message - A charge for a plain text message of up to 160 characters.

When you create your agent, choose the Billing Category that most closely matches the behavior of your agent logic:

  • Conversational - This agent engages in complex user interactions where messages are exchanged in both directions.
  • Single Message - This agent generally sends rich messages and seldom expects to receive replies.
  • Basic Message - This agent implements SMS upgrade to RBM and seldom expects to receive replies. Generally the agent is expected to send plain text messages of up to 160 characters. The agent is not restricted and can send richer content if desired, and will be billed accordingly if so.

Any agents you created before the Billing Category was introduced will be marked as Conversational Legacy and will continue to be treated as they were before. Contact to discuss making a change to a different Billing Category.

Create the agent

Before you do anything else, create your agent in the Business Communications Developer Console.

  1. Open the Business Communications Developer Console and sign in with your RBM Google account.
  2. Click Create agent.
  3. Enter your agent's name and region, then click Create agent.
  4. When your agent is available, click your agent's name.

Once your agent is available, you can add business and branding information. See Agents.

Create a service account key

To send messages and events as your agent, you need to authenticate API calls with a service account key. The Business Communications Developer Console creates a service account for you, but you need to create a unique key to access your agent.

  1. In the left navigation, click Service account.
  2. Click Create key, then click Create.
  3. Rename the downloaded key to "rbm-agent-service-account-credentials.json".
  4. Store the key in a secure location on your development machine. The key can't be recovered if lost.

Invite your test device

Now that you have an agent and your test device is RCS-enabled, you can invite your device to test your agent.

  1. In the left navigation, click Devices.
  2. For Add test devices, enter your device's phone number and click Add.
  3. On your test device, accept the tester request for your agent.

If you don't receive an invitation on your test device, verify that RCS is enabled on your device.

Send a message

With a registered test device, your agent can now send messages.

In a terminal on your development machine, run the following command.

  • Replace REGION with asia, europe, or us, depending on your agent's region.
  • Replace PHONE_NUMBER with the phone number of your test device. Include the country code, the area code, and a leading +, but don't include separators. For example, +14155555555.
  • Replace PATH_TO_SERVICE_ACCOUNT_KEY with the path to the key you created earlier.
curl -X POST "" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'contentMessage': {
    'text': 'Hello, world!'

You should receive a "Hello, world!" message from your agent on your test device.

If you don't receive a message on your test device, verify that you correctly entered and formatted the phone number and path to your service account key in the command.

Next steps

Now that your agent can send messages to a test device, it's time to build something that suits your business needs. Get a sample agent in your preferred language and follow the instructions in the sample's README.

Once you have the sample agent configured, review RBM's best practices and learn how agents send and receive messages.