> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a Voiceflow agent to RCS

> Connect RCS for Business to a Voiceflow text agent. Configure the platform, host the relay, test replies and prepare release.

## Overview

Answer customer text messages with a Voiceflow agent through Google’s RCS for Business APIs. Your registered RCS agent receives messages at a signed webhook, and your relay sends the reply to the same reachable device.

<a id="before-you-begin"></a>

## Before you begin

Collect the agent, account and host access.

| Requirement | Obtain before installation |
| --- | --- |
| Voiceflow owner | An existing agent with a known support answer, a private project API key, project ID and reviewed Environment alias. [Build the agent](/docs/documentation/build/overview) first, then [publish the intended release](/docs/documentation/deploy/environments/publishing). |
| Partner account | An approved RCS for Business partner account and an agent created for the intended brand, region and use case. |
| Service account | The partner’s service-account JSON key with access to the RCS agent; keep it outside the web root with mode 600. |
| Test device | An RCS-enabled device invited as a tester, with the invitation accepted before testing. |
| Relay operator | A Node.js host, public HTTPS hostname, private secrets and persistent disk; an operator who can investigate paused conversations. |

The example provides public-policy text support. Keep private Voiceflow and platform credentials on the host; a customer’s messaging identity does not authorize access to orders or account records. Have the agent return text only and provide a support route in its instructions. Buttons, audio and Handoff traces need additional adapters; see [Adapt agent replies](/docs/guides/channels/messaging/adapt-agent-replies).

<a id="create-platform-app"></a>

## Prepare the platform account

Create the exact app or account this relay will use.

### 1. Create the partner agent

Register with [RCS for Business](https://developers.google.com/business-communications/rcs-business-messaging/guides). In its Developer Console, create the brand’s agent, complete brand/contact information and choose the use case that matches customer support. Record the Agent ID. A Google Cloud project by itself does not grant partner or carrier access.

### 2. Prepare the service account and device

From the partner account settings, create or obtain its service-account credentials and download the JSON key securely to your host. Do not put it in the example archive or public directory. Invite your test device through the agent’s **Devices** settings and accept the invitation on the phone. Confirm that its messaging app and network support your test agent.

The relay signs a service-account JWT and exchanges it at Google’s OAuth token endpoint for the `https://www.googleapis.com/auth/rcsbusinessmessaging` scope. It caches only the resulting short-lived access token in memory and renews it before expiration. The webhook client token is a different secret.

<a id="run-relay"></a>

## Run the relay

Configure and host the supplied executable example.

Use the [configuration file](/docs/examples/messaging/rcs-for-business.env.example) for this platform. Every name below is read by the supplied artifact; IDs identify the resources prepared above. `VF_ENVIRONMENT` is the Environment alias, not a version label pasted from another project.

```dotenv
VF_API_KEY=YOUR_PRIVATE_VOICEFLOW_PROJECT_KEY
VF_PROJECT_ID=YOUR_VOICEFLOW_PROJECT_ID
VF_ENVIRONMENT=YOUR_ENVIRONMENT_ALIAS
DATA_DIR=/var/lib/voiceflow-messaging
PORT=8080
PLATFORM=rcs-for-business
RCS_AGENT_ID=YOUR_RCS_AGENT_ID
RCS_CLIENT_TOKEN=YOUR_RANDOM_CLIENT_TOKEN
GOOGLE_APPLICATION_CREDENTIALS=/opt/voiceflow-messaging/service-account.json
```

### 1. Download and configure the relay

On a Linux host you administer, create `/opt/voiceflow-messaging` and extract the [relay archive](/docs/examples/messaging/messaging-relay.zip) there. Use Node.js 22.12 or later. Run `node --test fixtures.test.mjs` first: it generates signed synthetic events and mocks all remote calls, without credentials or live messages. Save the configuration above as `.env`, replacing every `YOUR_` value; restrict it to the service account with `chmod 600 .env`. Set `DATA_DIR` to a private persistent directory that this account can write.

The archive includes `core.mjs`, platform adapters, HTTP/Teams entry points, local fixture tests and a package manifest. Run `node --env-file=.env relay.mjs serve`. The HTTP relay uses only Node built-ins; it does not need `npm install`.

### 2. Expose the HTTPS endpoint

Point your own DNS hostname to the host. Terminate HTTPS with a valid public certificate and proxy to `127.0.0.1:8080`. For example, with [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy) installed:

```sh
caddy reverse-proxy --from support.example.com --to 127.0.0.1:8080
```

Replace the example hostname, allow inbound 80/443 for certificate provisioning and keep the relay port private. Use a separate hostname and credentials for testing. Confirm `https://YOUR_HOST/health` returns `ok` before registering `/webhook`.

### 3. Keep one process running

After the foreground check, stop it and create a service using the unit below. Keep one process and one writable data directory per installation. Do not run this file store on ephemeral serverless storage or start multiple replicas.

```ini
# /etc/systemd/system/voiceflow-messaging.service
[Unit]
Description=Voiceflow messaging relay
After=network-online.target

[Service]
User=relay
WorkingDirectory=/opt/voiceflow-messaging
ExecStart=/usr/bin/node --env-file=.env relay.mjs serve
Restart=on-failure
UMask=0077

[Install]
WantedBy=multi-user.target
```

Create the non-login `relay` service user, give it read access to the application and `.env`, and ownership of `/var/lib/voiceflow-messaging`. Confirm `/usr/bin/node --version` is 22.12 or later, or substitute your actual Node path. Then run `sudo systemctl daemon-reload` and `sudo systemctl enable --now voiceflow-messaging`. Expect the service to stay active; keep the HTTPS proxy running through its own service.

The file store is a small single-process starting point. Back it up privately and monitor disk space, queue age and failures. Higher traffic needs a transactional inbox/outbox and per-conversation workers before adding replicas. Session keys and customer text are stored in the data directory; apply your retention and access policy there as well as in Voiceflow.

<a id="register-events"></a>

## Register incoming events

Connect the platform to your hosted endpoint.

### 1. Verify the RCS callback

In the RCS for Business Developer Console, open the agent’s **Integrations → Webhook → Configure**. Enter `https://YOUR_HOST/webhook` and a client token matching `RCS_CLIENT_TOKEN`. Choose **Verify**. The relay checks the verification request’s `clientToken` and returns its raw `secret` string.

### 2. Check signed message delivery

For event callbacks, it base64-decodes `message.data`, computes HMAC-SHA512 using the client token, compares `X-Goog-Signature`, and requires the decoded `agentId` to match. The digest is over the decoded bytes, not the outer JSON. It saves the event before returning 200 and runs the agent asynchronously. See [Google’s webhook contract](https://developers.google.com/business-communications/rcs-business-messaging/guides/integrate/webhooks).

Agent-specific webhooks override a partner-level webhook. Keep all partner callbacks healthy: Google’s partner queue can be affected by one failing agent endpoint. A verification success does not prove service-account permission to send.

<a id="conversation-routing"></a>

## Route conversations and replies

Keep the customer, agent session and reply destination aligned.

| Stage | Mapping in the example |
| --- | --- |
| Customer identity | RCS agent ID + `senderPhoneNumber`, scoped further by Voiceflow project and Environment. |
| Incoming text | Decoded `UserMessage` with `messageId` and `text`; other content receives a text-only notice. |
| Visible reply | POST `https://rcsbusinessmessaging.googleapis.com/v1/phones/{E.164}/agentMessages` with `agentId`, a stable UUID `messageId` per chunk, and `contentMessage.text`. |
| Duplicate and consent | Deduplicate inbound message IDs; receipts never run the agent. STOP/UNSUBSCRIBE/BAJA/PARAR text and unsubscribe events pause automation immediately; one fixed confirmation is queued per opt-out episode. |

The relay hashes platform, destination account, customer/thread, project and Environment into a bounded Voiceflow `userID`. It creates a session with the private project key, stores the returned `sessionKey`, launches once, then sends `{ action: { type: "text", payload: text } }` to `/v4/interact`. Text traces become platform replies. Follow-ups reuse the key; starting a session every message would reset the conversation.

Only devices reachable through the RCS platform can receive the reply; an unsupported or unreachable user can produce 404. API acceptance can queue a message for later delivery, so verify delivery/read events separately. Stable outbound UUIDs let Google suppress repeated send IDs. This sample does not add SMS fallback or rich cards.

Register the correct use case and honor [its business rules](https://developers.google.com/business-communications/rcs-business-messaging/guides/learn/agent-use-cases). After opt-out, do not resume a customer merely to retry an old answer. The sample sends “You have been unsubscribed and will not receive further messages.” without running the agent, then keeps AI replies suppressed. Google can send both STOP text and an UNSUBSCRIBE event for one action; the stored opt-out state prevents two confirmations. Consent is keyed by platform, RCS agent and customer, independently of the Voiceflow project or Environment; a release change does not restore permission. Before launching in another language, set `RCS_OPT_OUT_KEYWORDS` to additional comma-separated terms and `RCS_OPT_OUT_CONFIRMATION` to the approved fixed localized response (1–500 characters). Include the exact confirmation in [your launch submission](https://developers.google.com/business-communications/rcs-business-messaging/guides/launch/launch-approval#opt-out-description).

Any re-enrollment must use a verified consent process. After obtaining permitted consent, stop the service, discard obsolete queued replies, run `node --env-file=.env relay.mjs opt-in KEY`, then reset/resume that key as needed. The command only records the operator’s verified outcome; it does not obtain consent from Google or the customer.

Google can retry failed webhooks for up to seven days. Persist message IDs for at least the retry horizon and monitor delayed events. See [receive messages](https://developers.google.com/business-communications/rcs-business-messaging/guides/build/messages/receive) and [send message requirements](https://developers.google.com/business-communications/rcs-business-messaging/reference/rest/v1/phones.agentMessages/create).

<a id="test-conversation"></a>

## Test a customer conversation

Verify the reply in the destination you installed.

### 1. Send a real platform message

From the accepted RCS test device, message the agent’s approved test entry point with the support question. Expect the reply in the same RCS conversation.

### 2. Check continuity and isolation

Ask a related follow-up, then test with a second authorized customer. Confirm the intended Voiceflow project and exchange in [Transcripts](/docs/documentation/measure/transcripts). Run `node --env-file=.env relay.mjs inspect` while the service is stopped to compare event IDs, conversation keys and completion states without printing session tokens.

### 3. Check this platform’s delivery behavior

Check the inbound message ID, stable outbound UUID, delivery event and Voiceflow session. Send STOP and expect one fixed unsubscribe confirmation, no new agent turn and no later queued AI answer. Run the included paired STOP/UNSUBSCRIBE fixture to verify one confirmation across both callbacks.

A saved callback, accepted API request or successful Voiceflow Run does not prove this platform conversation. Keep local signed-fixture tests separate from this authenticated customer test.

<a id="troubleshooting" />

### The callback saves but no reply arrives

Check platform access as well as endpoint connectivity.

For 404, confirm tester invitation, RCS reachability, Agent ID and launch coverage. For 401/403, check the partner service account and JWT scope. For rejected callbacks, hash the decoded message bytes and compare client tokens.

### A conversation is paused or a reply is duplicated

Reconcile remote effects before resuming the saved job.

Inspect the event’s `phase`, `failedDuring`, saved traces and accepted chunks in the private data file. A runtime timeout can occur after a tool action; a send timeout can occur after the platform accepted the message. The sample pauses that conversation and does not retry either effect automatically. Follow [Recover failed messages](/docs/guides/channels/messaging/recover-failed-messages), then repeat the platform test.

<a id="go-live"></a>

## Release and maintain the connection

Promote the tested route and keep recovery available.

### 1. Approve the production destination

Complete brand verification and launch approval for the intended countries and carriers. Google-managed and carrier-managed launches have different requirements, including network/contract prerequisites; follow the Console’s launch checklist. Test the approved production route on an eligible device, not only an invited tester.

### 2. Release the reviewed agent

Have the Voiceflow owner publish the tested agent to the intended Environment. Deploy that alias and production credentials to the relay, restart its service and repeat the [customer test](#test-conversation) with a fresh customer/session. Existing session keys are not an automatic migration to a new release. Keep the previous deployment and state backup available for rollback.

### Rotate, update or disconnect

Maintain both the provider registration and the relay state.

Stop the service before changing `.env` or running maintenance commands. Rotate the platform credentials using its administrator controls, update the secret file and restart. If a webhook secret changes, update both sides and check a real event. For a release change, drain or reconcile pending jobs first; do not erase the state file to resolve a delivery problem.

To disconnect, disable/remove this callback or uninstall this app in the provider, stop the relay and revoke its unused credentials. Confirm no new events arrive and retain/delete customer state according to your policy. Keep the registration details needed to reconnect. See [Pause automated replies](/docs/guides/channels/messaging/pause-automated-replies) for a temporary conversation-specific pause.
