Users can start a conversation with your agent from an SMS deep link URL. Where
you place the URL depends on your use case. You might place it in an email, a
website, an app, or a physical location---wherever you can embed the URL as a
button, link, or QR code.

Manually navigating to an agent's URL (by copying and pasting it, for example)
doesn't work because of browser security measures. You must embed the URL in a
button, link, or QR code.

## The user experience

When the user opens your agent's URL, there are three possible outcomes:
success, fallback, or error.

### Success

The user enters a successful RBM conversation. For the conversation to start
successfully, all of the following criteria must be met:

- Google Messages is installed on their device (minimum version `messages.android_20241029_00`).
- RCS chats are enabled in Messages.
- Your RBM agent is launched on the user's carrier.

### Fallback

> [!NOTE]
> **Note** : To specify a fallback number, you need to [use the URL format with a phone number and service ID](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#format_1_use_a_phone_number_and_service_id).

The user is routed to a fallback phone number or shortcode. This occurs if *any*
of the success criteria are not met *and* a fallback number has been provided in
the URL.

### Error

The user sees an error message and a link to the
[Messages Help Center](https://support.google.com/messages/answer/7513219#zippy=%2Ctroubleshoot-conversation-not-available)
to explain why the agent may not be available and to help the user with
troubleshooting.

This occurs if *any* of the success criteria are not met *and* a fallback number
has *not* been provided.

## Create the agent URL

You can create URLs in two formats, as defined in
[GSMA RCC.07 v.14.0](https://www.gsma.com/solutions-and-impact/technologies/networks/wp-content/uploads/2024/06/RCC.07-v14.0.pdf),
section 3.6.3.4.

For security reasons, these formats don't support pre-filled suggested replies
or suggested actions within the URL.

### Format 1: Use only the service ID

       sms:bot%40botplatform.example.com?body=tell%20me%20about%20checking%20accounts

- `sms:bot%40botplatform.example.com`: Unique service ID for your agent.
- `&body=tell%20me%20about%20checking%20accounts`: Optional [pre-filled message](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#pre-filled_message) the user will see when they open the RBM conversation with your agent.

**Limitation** : This format can't include a fallback phone number. If an RBM
conversation can't be established, the user will receive an [error](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#error)
message.

### Format 2: Use a phone number and service ID

       sms:+15554443333?service_id=bot%40botplatform.example.com&body=tell%20me%20about%20checking%20accounts

- `+15554443333`: Phone number in E.164 format or valid short code associated with your agent.
- `service_id=bot%40botplatform.example.com`: Unique service ID for your agent.
- `body=tell%20me%20about%20checking%20accounts`: Optional [pre-filled message](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#pre-filled_message) the user will see when they open the RBM conversation with your agent.

**Limitation** : Some OEM camera apps (such as Samsung and Xiaomi) strip custom
query parameters like `service_id` when scanning raw `sms:` QR codes, which
causes the device to open a chat with the fallback phone number instead of your
RBM agent. When using Format 2 in a QR code, always encode an HTTPS short link
that redirects to the `sms:` URL (see [Best practices](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#best_practices)), or use
[Format 1](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#format_1_use_only_the_service_id) if a fallback phone number isn't
required.

## Pre-filled message

To provide a smoother user experience, you can pre-fill the message input field
when the RBM conversation opens. This allows users to quickly send a relevant
message by tapping the send button.

To include a pre-filled message, use the `body` parameter in the URL. The body
parameter must be URL-encoded. For example, spaces should be replaced with
`%20`.

The message should align with the user's intent and your brand's goals. Here's
an example from a wellness brand:
`sms:bot%40botplatform.example.com?body=make%20an%20appointment.` When the user
taps this link, their messaging app will open the chat with the pre-filled
message "Make an appointment."

![Pre-filled message](https://developers.google.com/static/business-communications/rcs-business-messaging/images/pre-filled-message.png)

## Best practices

When incorporating QR codes into your brand's materials, always create a short
link that redirects users to the agent URL (for example, <https://short.link/abc123>).
Here are the benefits of using a short link:

- **Future-proofing**: You can update the agent URL behind the short link if needed, with no need to reprint materials with a new QR code.
- **Seamless fallback**: Prevent user confusion about the URL if they're redirected to a fallback option.
- **Cross-device QR compatibility** : Prevent OEM camera apps (such as Samsung and Xiaomi) from stripping the `service_id` parameter when scanning QR codes that include a fallback phone number.

## Test on dual-SIM devices

If a device has more than one SIM or eSIM, Google Messages uses only one SIM to
check whether your agent is available. Google Messages selects the first active
SIM that has RCS chats turned on. If no SIM has RCS chats turned on, Google
Messages uses the SIM in the first slot. If your agent isn't launched on the
carrier of the selected SIM, and the phone number of that SIM isn't a
[test device](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/test#tester-request),
the user sees the [error](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#error) or [fallback](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#fallback) result. This happens
even if your agent is launched on the carrier of the other SIM.

To get reliable results when you test your agent URL on a dual-SIM device, do
one of the following:

- Register the phone number of each SIM on the device as a [test device](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/test#tester-request) for your agent.
- Turn off the SIMs that you don't test with. Then force stop Google Messages, open it again, and open your agent URL.

Users with dual-SIM devices can also see this result. To give these users a
path to your business, use
[Format 2](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/deeplinks#format_2_use_a_phone_number_and_service_id) with a fallback phone
number.

## SMS link creator

To create an SMS link and generate a QR code for your agent, enter the following
information and then click **Create SMS Link**:

- **Agent ID** (required). Your agent ID can be found in the Agent overview in the [RCS for Business Developer Console](https://business-communications.cloud.google.com?utm_source=/business-communications/rcs-business-messaging/guides/build/deeplinks&utm_medium=devsite&utm_campaign=rcs-business-messaging).
- **Fallback Phone Number** (optional).
- **Draft message** (optional).

<iframe src="https://developers.devsite.google/frame/business-communications/rcs-business-messaging/guides/build/deeplinks/index_c518ad8fa7a9c68df5865f3d99bd209e4c9a5d76eed221c465afca41cffe50a7.frame" class="framebox inherit-locale " allow="clipboard-write https://developers.devsite.google" allowfullscreen is-upgraded></iframe>