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.
Before you begin
Collect the agent, account and host access.
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.
Prepare the platform account
Create the exact app or account this relay will use.
Create the partner agent
Register with RCS for Business. 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.
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.
Run the relay
Configure and host the supplied executable example.
Use the configuration file 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.
Download and configure the relay
On a Linux host you administer, create /opt/voiceflow-messaging and extract the relay archive 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.
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 installed:
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.
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.
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.
Register incoming events
Connect the platform to your hosted endpoint.
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.
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.
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.
Route conversations and replies
Keep the customer, agent session and reply destination aligned.
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. 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.
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 and send message requirements.
Test a customer conversation
Verify the reply in the destination you installed.
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.
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. 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.
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.
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, then repeat the platform test.
Release and maintain the connection
Promote the tested route and keep recovery available.
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.
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 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 for a temporary conversation-specific pause.