Overview
Answer messages to a verified WeChat Service Account with a Voiceflow agent through Sinch Conversation API. Sinch owns the WeChat callback and encryption; your relay receives signed Sinch callbacks and sends the agent’s text replies through the same account.
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.
Prepare the Service Account
In WeChat Official Accounts Platform, confirm that Type is Service Account and its verification is complete. Subscription accounts, Work/WeCom accounts and an ordinary personal account are not this setup. Obtain administrator approval for the API connection.
Configure Sinch and WeChat together
Create a Conversation API app in Sinch Build Dashboard and set its processing mode explicitly to CONVERSATION so callbacks have contact and conversation IDs. Open Set up channels → WeChat.
In WeChat’s Basic configuration, copy Developer ID (AppID) and Developer Password (AppSecret) into Sinch’s matching fields. Open Change Configuration and generate a Token and EncodingAESKey if needed. Enter the same Token and AES key in Sinch. Save the Sinch channel, then copy the callback URL it displays into WeChat’s URL field. Select Security Mode, submit the WeChat configuration and enable it.
Sinch, rather than this relay, verifies/decrypts the WeChat-side callback and owns its prompt acknowledgment. Do not paste your relay URL into WeChat: it accepts signed Sinch JSON, not WeChat XML. See Sinch’s account and configuration requirements.
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.
Register the Sinch webhook
In the Sinch app, add a Conversation API webhook targeting https://YOUR_HOST/webhook. Select MESSAGE_INBOUND and MESSAGE_DELIVERY, set a secret matching SINCH_WEBHOOK_SECRET, and save it. Keep the WeChat callback URL configured to Sinch’s adapter. These are two separate webhook registrations.
Check the callback contract
The relay checks the timestamp and verifies the base64 HMAC-SHA256 of raw-body.nonce.timestamp using Sinch’s x-sinch-webhook-signature-* headers. It requires the configured project and app IDs. A webhook without the secret cannot pass validation. Sinch retries temporary connection, 5xx and 429 failures; ordinary 4xx rejections are not generally retried. See Sinch callbacks.
Save a test callback privately and confirm direction: TO_APP, channel_identity.channel: WECHAT, nonempty contact_id and conversation_id. Empty IDs usually mean the app is still in Dispatch mode.
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.
Sinch documents a 48-hour window after the customer’s last message and a limit of 20 ordinary messages to that person during the window. This sample answers immediately, uses 500-character chunks, and has no template-message route. Keep replies brief and check the provider’s remaining allowance; the sample does not maintain a distributed account-wide quota counter. See WeChat message support.
Sinch’s send response confirms acceptance, not handset delivery. Inspect delivery callbacks for rejection, account eligibility or expired-window errors. Other WeChat products and direct XML/API integrations have different setup and are not implemented here.
Direct WeChat integration: A direct developer connection would need its own verification, XML/AES handling, access-token lifecycle and reply strategy. That alternative is not supplied by this walkthrough. Chat agents documents the Voiceflow side only.
Test a customer conversation
Verify the reply in the destination you installed.
Send a real platform message
Scan the Service Account’s QR code in WeChat, follow the account and send your prepared text question. Expect an agent reply from that Service Account.
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 a real inbound message, rather than only the follow/opt-in callback. Confirm the contact and conversation IDs survive a follow-up and that a duplicate signed Sinch fixture does not run the agent twice.
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.
Compare the WeChat AppID, secret, Token, AES key and Security Mode with the saved Sinch channel. Check that WeChat points to Sinch, while Sinch points to your relay. Confirm Conversation mode, channel eligibility and the ordinary-message allowance.
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
Have the account administrator confirm verification and regional eligibility with Sinch. Use the production app and credentials, verify both callback registrations and test on an authorized WeChat device. Any provider review or commercial activation remains a prerequisite.
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.