Overview
This developer-led walkthrough connects SMS SDK with Event Grid to an existing Voiceflow Chat agent. Your server receives customer texts, selects the intended agent session, sends the text to Voiceflow, then delivers the answer through Azure Communication Services. You host and maintain the relay; a provider send action alone does not establish this conversation path.
Managed alternative: Voiceflow SMS hosts the two-way channel for connected Twilio numbers. This page teaches the Azure Communication Services relay.
Before you begin
Prepare the agent, provider account and relay host.
An Azure subscription eligible for SMS, a Communication Services resource and a phone number with Send and receive SMS capability. The event subscription owner needs permission to subscribe to the resource’s events. This recipe uses Event Grid schema, not CloudEvents schema.
Examples use 🇺🇸 US +14155550100 as the business number and +12025550123 as the customer. Replace these fictional numbers with your controlled, eligible numbers. Use the provider’s required international representation at its boundary; the relay stores normalized E.164.
This sample handles incoming-first text support, one provider and one business number per deployment. It returns text traces, suppresses the launch greeting, and sends one answer of at most 640 UTF-16 units. It does not implement MMS, rich controls or human agent hand-off. Review Chat agents before extending those behaviors.
Host the relay
Install the server and connect its persistent store and credentials.
Download the runnable relay
Download the SMS relay archive and unpack it on the host:
The archive includes the server, provider adapters, SQLite worker, pinned dependency lock, Docker/HTTPS configuration and offline tests. The README owns the shared operations and recovery commands.
Configure the agent and secrets
Edit .env: set PROVIDER=azure, SMS_DOMAIN to your domain, PUBLIC_ORIGIN to its HTTPS origin without a trailing slash, and SMS_FROM to the owned E.164 business number. Set VF_PROJECT_ID, VF_ENVIRONMENT and VF_API_KEY to the published test Chat Environment and its runtime key. These are server secrets, never browser inputs.
Generate two separate random values with the following command, putting one in IDENTITY_SECRET and the other in WEBHOOK_SECRET. Set ROUTE_GENERATION=1.
Keep IDENTITY_SECRET stable so sender identity and local opt-out records survive restarts. Add this provider’s variables:
Remove the unused Telnyx entries from .env.example when selecting another provider. AWS SDK credentials, when needed, follow the credential-chain instructions in the provider setup below.
Start and check the HTTPS receiver
Point the domain’s DNS at the host, then run:
Replace YOUR_SMS_DOMAIN with SMS_DOMAIN. Caddy obtains TLS and proxies to the private relay port. Expect {"ok":true} from health. Keep the sms-data volume: it stores message IDs, session keys, pending replies and suppression records. Do not scale this SQLite example to several processes.
Your callback URLs are https://YOUR_SMS_DOMAIN/inbound/WEBHOOK_SECRET and https://YOUR_SMS_DOMAIN/status/WEBHOOK_SECRET, substituting the actual secret value. Call these INBOUND_URL and STATUS_URL below. Do not include the literal variable names in the provider settings or enable access logs containing the secret. Do not redirect either callback URL.
Connect Azure Communication Services
Save the provider’s incoming route and prepare outgoing replies.
Create the Event Grid subscription
In Azure Portal, open the Communication Services resource, select Events → Add Event Subscription, and name the subscription. Choose Event Grid Schema and event type SMS Received (Microsoft.Communication.SMSReceived). For Endpoint type, choose Web Hook, then enter INBOUND_URL.
Complete endpoint validation
Set AZURE_TOPIC to the full Communication Services resource ID from Properties, and start the relay before saving the subscription. The handler checks the secret URL and topic, then returns data.validationCode as validationResponse for the subscription-validation event. In Azure, choose Confirm Selection, then Create. Confirm provisioning succeeds.
Route delivery reports separately
Create a second Event Grid subscription with event type SMS Delivery Report Received, endpoint STATUS_URL and the same Event Grid schema. The SDK sends with enableDeliveryReport:true. The status handler stores receipts and never forwards them as customer text.
The high-entropy endpoint URL is a bearer secret over HTTPS; the handler also verifies the Event Grid topic. Event Grid validation proves endpoint ownership, not a provider signature. Protect the URL in subscription settings and proxy logs. This recipe does not implement Entra-authenticated webhook delivery; an organization requiring it must add its token validation before changing this configuration.
Map messages and sessions
Keep the sender, agent release and reply direction consistent.
The server calls POST /v4/project/{projectID}/environment/{alias}/session with the runtime API key, then POST /v4/interact with the returned session token. The session and interact references own the full contracts. This route uses the Environment’s Published release; compiling a Draft alone does not release it. Transcripts identify these relay sessions as API conversations.
Test a customer conversation
Verify the real incoming text, agent session and delivered reply.
Run the offline checks
Before installing real provider credentials, run the archive’s tests with Node 22.13 or later:
These tests use synthetic provider events and mocked agent/sender responses. They check mappings, signatures, duplicate handling and restart behavior without sending a message. They do not establish live provider acceptance.
Send the known question and follow-up
From your separate phone, text “What are your collection hours?” to the Azure Communication Services business number. Expect the prepared answer, for example “Northstar collection hours are 10 am to 6 pm.” Reply “Are you open at noon?” and check that the answer uses the same conversation. Inspect the intended project’s Transcripts. Confirm no launch greeting is sent separately.
Compare ingestion, sending and receipt
Inspect docker compose logs relay for the hashed job ID and phase:"accepted", then use the retained provider ID/reference to find the outgoing message. Confirm its sender is the business number, its recipient is the customer, and the phone receives one answer per turn.
Retain the SDK’s messageId only when successful:true. Inspect the SMSDeliveryReportReceived event’s data.deliveryStatus (Delivered or Failed) and details, then check the handset. Event Grid redelivery can repeat a notification; the incoming message ID deduplicates it.
Exercise continuity and recovery
Send a new question after restarting only the relay container; the stored session should continue. On a controlled recipient, test the configured STOP/START/HELP route and verify STOP prevents an agent send. Re-submit a captured authorized synthetic fixture only to a local/offline test receiver to check duplicate behavior; do not replay a production callback, which can trigger paid messages. Test a second customer to confirm their context remains separate.
The provider has the text but the relay has no job
Check the saved incoming route, callback authorization and payload family.
Check the provider configuration against this manual, including number ownership, active subscription/application and exact URL. Inspect provider callback errors and relay container health. A 401 indicates callback authorization; a 400 indicates malformed incoming fields or the wrong schema; a temporary 503 means the local store could not commit. Other event types are acknowledged with 200 without creating a conversation, so verify an incoming job in the ledger as well as the callback status. Keep the provider’s event ID and timestamp. Fix the saved configuration before sending another controlled text.
The relay records uncertain or held work
Resolve the original remote outcome before allowing another attempt.
Inspect the job with the README’s inspect command, the corresponding Transcript and provider log. An agent tool or send might have succeeded before its response was lost. The worker does not automatically retry this job and holds later messages for that conversation. Resolve the original outcome, then use the explicit recovery command; never clear the database to force a resend.
The provider accepts the reply but the phone gets nothing
Check delivery evidence, sender eligibility and recipient suppression.
Find the exact outgoing ID/reference in the provider log, inspect final delivery status and errors, and confirm the destination, sender registration, balance, country permissions and opt-out state. An accepted request is not a delivery receipt. If the account rewrites the sender, correct its two-way routing before launch.
Release and maintain the channel
Cut over the provider number and the published agent together.
Release the reviewed agent and relay
Publish the reviewed Chat Environment. Stop inbound routing temporarily or schedule the cutover, let queued work drain, and back up the persistent volume. Set the final VF_PROJECT_ID/VF_ENVIRONMENT and increase ROUTE_GENERATION to start fresh sessions on this deployment configuration. Recreate the relay container with docker compose up -d. The program refuses a route change while old queued jobs remain.
Verify the production route
Repeat the known question and follow-up through the final Azure Communication Services number. Check the Published instructions, provider sender, destination and final delivery evidence. Keep the earlier route ready until this acceptance succeeds.
Update or disconnect the relay
Coordinate secrets, provider routing and the persistent message ledger.
Rotate a provider credential in .env, recreate the container and repeat the customer test. Rotate a webhook token/signing secret with the provider endpoint in the same change window. Keep IDENTITY_SECRET and the persistent volume stable; replacing them resets local sender identity and suppression history.
To stop this channel, disable the provider’s route/subscription first, then stop the worker after queued jobs drain. Restore the recorded prior provider route if required. Keep the volume/backup according to your data-retention policy; docker compose down -v deletes the message ledger and is not a recovery step. Number release and billing cancellation remain provider-account actions.