Build your first agent

Users interact with agents through an RCS-enabled messaging app, such as Google Messages, on their devices. In this quickstart, 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

Prerequisites

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

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 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 basic information.

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.

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.

The following two categories never create conversational billing events. Carriers will charge a Basic Message or Single Message price for each message, depending on the content that is delivered.

  • 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. But the agent is not restricted; it can send richer content if programmed to do so, and will be billed accordingly.

You can change your agent's billing category before you launch your agent. Contact us to discuss changing to a different billing category.

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.

You cannot change the use case after your agent has been submitted for launch. Be sure to review use cases and business rules for your country prior to submitting your agent.

Create the agent

Follow these instructions to create your agent in the Business Communications Developer Console.

  1. Open the Business Communications Developer Console and sign in with your RBM partner Google Account.
  2. Click Create agent.
  3. For Agent type, select RCS Business Messaging.
  4. For Brand, select the brand your agent will represent, or click Add new brand and enter its name.
  5. Enter your agent's name and select your agent's region, billing category, and use case. Then click Create agent.
  6. When your agent is available, click your agent's name.

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

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.

You need a service account key to securely authenticate API calls. If you haven't already created a service account key for your partner account, now is the time to do it.

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

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-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!"
  }
}'
  • 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 AGENT ID with your agent ID, located on the Agent information page in the Business Communications Developer Console.
  • Replace PATH_TO_SERVICE_ACCOUNT_KEY with the path to the key you created earlier.

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.

To send different types of messages, such as suggested replies and rich cards, see Send messages.

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.

Previous
Set up your partner account