Google RCS Business Messaging API: Developer Guide 2026

Google's RCS Business Messaging (RBM) API is the programmatic interface for sending rich, verified business messages to Android users. This guide is for developers and technical architects who need to understand how the API works, how to authenticate, how to send different message types, and how to handle incoming messages and delivery events through webhooks. We also cover common error patterns and how to implement robust fallback behavior.

Overview: What is the RCS Business Messaging API?

The RCS Business Messaging API is a RESTful HTTP API hosted by Google as part of its Business Communications platform. It allows a registered business agent (your brand's verified RCS identity) to send messages to end users who have opted in and whose devices and carriers support RCS. The API supports unidirectional (business-to-consumer) and bidirectional (two-way conversation) messaging.

The API endpoint base URL is: https://rcsbusinessmessaging.googleapis.com/v1/

All API operations require a valid OAuth2 access token obtained using a Google Cloud service account with the Business Messages API scope.

Authentication Setup

Step 1: Create a Google Cloud Project

Navigate to the Google Cloud Console and create a new project. Enable the "RCS Business Messaging API" in the API Library. This provides access to the API quota and credentials management.

Step 2: Create a Service Account

Under IAM & Admin, create a service account for your application. Grant it the "RCS Business Messaging Editor" role. Generate a JSON key file - this file contains the credentials your application will use to authenticate.

Step 3: Obtain an Access Token

Use the service account JSON key to generate a short-lived OAuth2 access token. The token has a 1-hour expiry and should be refreshed automatically by your application. Here is the token request structure:

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<signed_jwt>"
}

The signed JWT must include the scope: https://www.googleapis.com/auth/rcsbusinessmessaging

Sending a Simple Text Message

The basic text message endpoint is a POST to:

POST /v1/phones/{msisdn}/agentMessages

Where msisdn is the recipient's phone number in E.164 format (e.g., +919228818877). The request body:

{
  "messageId": "unique-message-id-001",
  "agentMessage": {
    "contentMessage": {
      "text": "Hello! Your order #12345 has been confirmed."
    }
  }
}

Include the Authorization header: Authorization: Bearer <your_access_token>

A successful response returns HTTP 200 with the message resource object. Store the name field from the response - you will need it to correlate delivery status events from webhooks.

Sending a Rich Card

Rich cards are the most common RCS message format for marketing use cases. The richCard object replaces the text field in the contentMessage:

{
  "messageId": "rich-card-001",
  "agentMessage": {
    "contentMessage": {
      "richCard": {
        "standaloneCard": {
          "cardOrientation": "VERTICAL",
          "thumbnailImageAlignment": "RIGHT",
          "cardContent": {
            "title": "Summer Sale - 40% Off",
            "description": "Shop our biggest sale of the year. Ends Sunday.",
            "media": {
              "height": "TALL",
              "contentInfo": {
                "fileUrl": "https://example.com/images/summer-sale.jpg",
                "forceRefresh": false
              }
            },
            "suggestions": [
              {
                "action": {
                  "text": "Shop Now",
                  "postbackData": "cta_shop_now",
                  "openUrlAction": {
                    "url": "https://example.com/sale"
                  }
                }
              },
              {
                "reply": {
                  "text": "Not interested",
                  "postbackData": "cta_opt_out"
                }
              }
            ]
          }
        }
      }
    }
  }
}

Sending a Carousel

Carousels use the carouselCard type, which contains an array of card content objects. Each card in the carousel can have its own image, title, description, and action buttons:

{
  "agentMessage": {
    "contentMessage": {
      "richCard": {
        "carouselCard": {
          "cardWidth": "MEDIUM",
          "cardContents": [
            {
              "title": "Product A",
              "description": "Rs. 1,299",
              "media": {
                "height": "MEDIUM",
                "contentInfo": {"fileUrl": "https://example.com/product-a.jpg"}
              },
              "suggestions": [{"action": {"text": "Buy Now", "postbackData": "buy_product_a", "openUrlAction": {"url": "https://example.com/product-a"}}}]
            },
            {
              "title": "Product B",
              "description": "Rs. 899",
              "media": {
                "height": "MEDIUM",
                "contentInfo": {"fileUrl": "https://example.com/product-b.jpg"}
              },
              "suggestions": [{"action": {"text": "Buy Now", "postbackData": "buy_product_b", "openUrlAction": {"url": "https://example.com/product-b"}}}]
            }
          ]
        }
      }
    }
  }
}

Receiving Messages with Webhooks

To receive inbound messages (when users reply), you configure a webhook URL in the Business Communications Developer Console. Google sends POST requests to your endpoint whenever a user sends a message, taps a suggestion, or an event occurs.

Webhook Payload Structure

A user reply payload looks like this:

{
  "senderPhoneNumber": "+919228818877",
  "sendTime": "2026-01-15T10:30:00Z",
  "messageId": "reply-msg-xyz",
  "text": "Yes, I am interested"
}

A postback (button tap) payload includes the postbackData value you defined in the suggestion:

{
  "senderPhoneNumber": "+919228818877",
  "sendTime": "2026-01-15T10:31:00Z",
  "suggestionResponse": {
    "postbackData": "cta_shop_now",
    "text": "Shop Now"
  }
}

Webhook Verification

Google signs webhook payloads with an HMAC-SHA512 signature. Always verify the X-Goog-Signature header before processing webhook data to ensure the request genuinely originated from Google's servers.

Error Handling and Rate Limits

Default rate limits are 600 messages per minute per agent. Common error responses and how to handle them:

• HTTP 429 (Too Many Requests): You have exceeded the rate limit. Implement exponential backoff with jitter. Start with a 1-second delay and double on each retry, up to 32 seconds.
• HTTP 400 (Bad Request): Payload validation failed. Check the error message in the response body - typically a missing required field or incorrect media URL format.
• HTTP 403 (Forbidden): Authentication error. Refresh your access token and retry.
• HTTP 404 (Not Found): The recipient's phone number is not RCS-capable. Implement fallback to SMS via your aggregator.

Using an Aggregator vs. Direct API Integration

Direct integration with the Google RCS Business Messaging API gives you maximum control but requires significant engineering effort - authentication management, rate limit handling, webhook infrastructure, DLT compliance in India, fallback SMS routing, and delivery reporting. Most businesses sending fewer than 10 million messages per month benefit from using an aggregator like RCSBulkSMS, which wraps all of this complexity in a simpler API and provides managed infrastructure for carrier routing and compliance.