Skip to main content

Azure Communication Services SMS Integration

Connect your own Azure Communication Services phone number to give AI agents bidirectional SMS capabilities - agents can receive inbound texts, maintain conversation context, and send outbound messages with safety-first controls.

info

New Azure Communication Services phone numbers cannot be bought from October 2026. New customers should connect a Twilio number instead; see Twilio SMS Integration.

Overview​

The Azure Communication Services (ACS) SMS Integration is a Bring Your Own Service (BYOS) model: you connect your existing ACS resource, and the platform assigns a dedicated phone number to an agent. That agent handles both inbound messages (arriving via Event Grid webhook) and outbound messages (sent via the ACS SMS send tool).

The ACS integration is purpose-built for bidirectional SMS. It provides one focused tool, the ACS SMS send tool, with full conversation history, deduplication, and daily health monitoring.

Outbound sends are disabled by default. An admin must explicitly enable them before agents can send any messages - giving you full control over autonomous communication.

info

One ACS phone number maps to one agent. This creates a dedicated line for that agent's SMS conversations, so the agent always has clear ownership of inbound messages and conversation context.

Use Cases​

  • Customer Support via SMS - Customers text a support number and an AI agent responds with context-aware answers based on full conversation history
  • Appointment Reminders - Agent proactively sends SMS reminders for upcoming appointments to customers
  • Order Status Updates - Agent sends shipping and delivery notifications via text
  • Two-Way Conversations - Agent maintains a running conversation thread with the last 10 messages of history
  • Urgent Notifications - Agent escalates important information via SMS when email may be too slow
  • Field Service Coordination - Agent coordinates with field workers who may only have SMS access

How It Works​

Admin connects ACS          1 tool created                 Inbound SMS arrives
via connection string        and assigned to agent          via Event Grid
       |                            |                              |
       v                            v                              v
+-----------------+       +---------------------+       +---------------------+
| Enter connection|       | ACS SMS send tool   |       | Webhook receives    |
| string, phone   |  -->  |                     |  -->  | event, queues it,   |
| number, agent   |       | Sends outbound SMS  |       | agent processes     |
| name            |       | with E.164 format   |       | with last 10 msgs   |
|                 |       | and 160-char limit  |       | of history          |
+-----------------+       +---------------------+       +---------------------+

Getting Started​

Prerequisites​

Before connecting ACS SMS:

  1. Active ACS Resource - You need an Azure Communication Services resource with at least one phone number provisioned in E.164 format (e.g., +15551234567)
  2. ACS Connection String - Available in the Azure Portal under your ACS resource > Keys. Copy the full connection string.
  3. Subscription Plan - The ACS SMS integration requires the Workforce or Platform plan
  4. Control Bridge Admin Access - You must be a Control Bridge administrator to configure the integration
  5. Event Grid Configuration - After connecting, you must manually configure an Event Grid subscription on your ACS resource to deliver inbound SMS events to the Outermind webhook (detailed in Step 3 below)
warning

Event Grid setup is a manual step performed in the Azure Portal. The platform does not auto-create Event Grid subscriptions on your ACS resource. Without this step, inbound SMS will not be received. See the Event Grid setup section below for full instructions.

Step 1: Connect ACS​

  1. Navigate to Capabilities > Connections > + Add Connection and choose Azure Communication Services SMS. Once connected, it is listed under Capabilities > Connections.
  2. Click Connect ACS SMS
  3. Enter a Connection Name (friendly label for this connection, max 100 characters)
  4. Paste your ACS Connection String (copied from the Azure Portal)
  5. Enter your Phone Number in E.164 format (e.g., +15551234567)
  6. Select the Agent that will handle inbound SMS and have the send tool. For Personal Assistants, the dropdown displays the employee name alongside the PA name (e.g., "Sales PA - Jane Smith") so you can easily identify which PA belongs to which employee.
  7. Click Connect

The system validates the connection string format and encrypts it at rest. The ACS SMS send tool is created and assigned to the selected agent automatically.

tip

Your ACS connection string is found in the Azure Portal under your Communication Services resource > Settings > Keys. Use either the Primary or Secondary connection string - both work. Copy the full string including the endpoint and access key.

Step 2: Enable Autonomous Sends (Optional)​

After connecting, decide whether the agent can send SMS messages autonomously:

  1. On the connection page, locate the Safety Controls section
  2. The Allow Autonomous Sends toggle is OFF by default
  3. When disabled, the agent cannot send outbound SMS - it will indicate it cannot send and ask for human escalation instead
  4. To enable outbound sending, toggle Allow Autonomous Sends to ON and confirm the dialog
warning

When autonomous sends are enabled, agents can send SMS messages without human confirmation. Outbound messages incur per-message charges on your ACS account. Only enable this after you are confident in your agent's instructions and have tested inbound processing.

Step 3: Configure Event Grid (Required for Inbound SMS)​

This step is performed entirely in the Azure Portal. Without it, inbound SMS messages will not reach the platform.

3a. Find Your Webhook URL​

Each connection has its own Event Grid delivery secret. The full webhook URL, including that secret, is shown once on the ACS SMS connection page in Control Bridge - right after you connect, or after clicking Rotate webhook secret on an already-connected number. Copy it immediately; it is not displayed again, and the page shows only the secret-less endpoint afterward.

The URL has the shape:

https://{your-region}-api.outermind.ai/api/webhooks/acs/sms?sig={your-connection-secret}

If you lose the secret, click Rotate webhook secret on the connection page to mint a new one, then update the Event Grid subscription's endpoint in the Azure Portal - rotating invalidates the previous URL immediately.

3b. Create the Event Grid Subscription​

  1. Open the Azure Portal and navigate to your Azure Communication Services resource
  2. In the left menu, select Events
  3. Click + Event Subscription
  4. Fill in the subscription details:
FieldValue
NameA descriptive name (e.g., outermind-sms-inbound)
Event SchemaEvent Grid Schema
Event TypesCheck both SMS Received (Microsoft.Communication.SMSReceived) and SMS Delivery Report Received (Microsoft.Communication.SMSDeliveryReportReceived)
Endpoint TypeWeb Hook
EndpointYour Outermind webhook URL (from Step 3a)
  1. Click Create

Azure will immediately send a validation request to the webhook. The platform handles the validation handshake automatically - no action is required on your side.

3c. Verify the Subscription​

After creating the subscription:

  1. Refresh the Events page in the Azure Portal
  2. Your subscription should show as Active with no errors
  3. Send a test SMS to your ACS phone number from a personal phone
  4. Check Governance > Activity History > Agent Runs to confirm the agent received and processed the message
tip

If the Event Grid subscription shows a validation error, check that your Outermind webhook URL is correct and that the endpoint is publicly reachable. The URL must use HTTPS.

Managing the Connection​

Update Credentials​

To rotate your ACS connection string without disconnecting:

  1. Navigate to Capabilities > Connections > ACS SMS
  2. Click Update Settings
  3. Paste the new connection string
  4. Click Save

The connection status resets to active when a new connection string is saved. Agent tool assignments and conversation history are not affected.

Reassign the Agent​

To change which agent handles inbound SMS:

  1. Navigate to Capabilities > Connections > ACS SMS
  2. Click Update Settings
  3. Select a different agent from the Assigned Agent dropdown. Personal Assistants show the associated employee name for easy identification.
  4. Click Save

The ACS SMS send tool is reassigned to the new agent. Previous conversation history in Table Storage is retained and associated with the phone number.

Disconnect​

To disconnect the ACS integration:

  1. Navigate to Capabilities > Connections > ACS SMS
  2. Click Disconnect and confirm the dialog

Disconnecting performs a soft-delete: the connection row is retained for audit purposes, but the encrypted connection string is cleared and the ACS SMS send tool is removed from the agent. Conversation history in Table Storage is also retained.

After disconnecting, the filtered unique index is freed so you can reconnect with a new ACS resource if needed.

warning

After disconnecting, remember to also delete or disable the Event Grid subscription in the Azure Portal. Otherwise, Azure will continue sending SMS events to the webhook, which refuses them with 401 (the webhook logs a warning for each event to a phone number it no longer recognizes, and never processes it).

AllowAutonomousSends Safety Toggle​

The autonomous sends toggle is the primary safety control for outbound SMS. It is stored as a separate field on the connection and can only be changed via the dedicated safety controls section - it is not part of general connection updates.

SettingBehavior
Disabled (default)The ACS SMS send tool returns an error instructing the agent to escalate to a human. No SMS is sent.
EnabledThe agent can send SMS messages autonomously. Messages are sent immediately and charged to your ACS account.

Toggling this setting requires a confirmation dialog in Control Bridge. The change takes effect immediately.

How Inbound SMS Processing Works​

When a text message arrives at your ACS phone number, the following sequence occurs:

  1. Event Grid delivers the event - Azure sends a Microsoft.Communication.SMSReceived event to POST /api/webhooks/acs/sms
  2. Webhook validates and queues - The platform verifies the event is for a registered phone number, then enqueues it to the sms-notifications Azure Storage Queue
  3. Queue processor picks it up - The SMS processor dequeues the message with exponential backoff (up to 3 retries)
  4. Deduplication check - The processor checks Azure Table Storage for the message ID. If the same message was delivered twice (Event Grid at-least-once delivery), the duplicate is silently discarded
  5. Conversation history loaded - The last 10 messages (both inbound and outbound) for this phone number pair are fetched and injected into the agent context
  6. Agent executes - The agent receives the message body, sender number, and conversation history, then processes and optionally responds

Texts From Your Own Employees​

When the agent handling your number is not a Personal Assistant and a text comes from a number that belongs to exactly one enabled user in your Microsoft Entra directory (their mobile or business phone), the agent sees that person's name marked as an unverified directory match and may text an answer back to that number only. Where SMS opt-in is available, the platform also sends that person (on a +1 number) one informational text from your number, at most once every 30 days, pointing them to the Mobile SMS opt-in on their Outermind Profile. Nobody is opted in by text: replying YES to it does not opt them in, and STOP opts them out. A Personal Assistant answers only numbers it texted first or users who opted in to SMS from their own profile, so a directory match does not reach it.

Inbound Message Context​

The agent receives the following information for each inbound SMS:

  • Sender phone number (the customer's number)
  • Message body
  • Timestamp
  • Conversation history - last 10 messages labeled [INBOUND] or [OUTBOUND] in chronological order

How Outbound SMS Works​

When the agent calls the ACS SMS send tool, the following happens:

  1. Safety gate check - If AllowAutonomousSends is disabled, the tool returns an error immediately. No send attempt is made.
  2. Phone number normalization - The recipient number is normalized to E.164 format (e.g., 5551234567 becomes +15551234567)
  3. Message truncation - If the message exceeds 160 characters, it is truncated to 157 characters with ... appended
  4. Send via ACS - The platform decrypts your connection string, creates an SMS client, and sends the message
  5. History recorded - The outbound message is stored in Table Storage for conversation history (non-blocking, fire-and-forget)
  6. Delivery report - Every send requests an ACS delivery report. When it arrives (an SMS Delivery Report Received event on the same webhook), the stored message's status moves from sent to delivered or failed, with the carrier's error code. If the carrier reports that the recipient has opted out of your number (error code 4007), the platform records an opt-out for that number, and later sends to it are refused until the recipient texts START. Delivery reports are applied directly and never start an agent run

The tool returns the message ID on success. If normalization changed the phone number format or truncation was applied, the tool also returns the original values so the agent can include them in its response.

tip

Write your agent instructions to inform recipients of the 160-character SMS limit for important messages. If a message needs to be longer, have the agent break it into multiple sends or direct the recipient to email or a longer channel.

Conversation History​

Every inbound and outbound message is stored in Azure Table Storage keyed by your ACS phone number and the remote phone number. When a new inbound message arrives, the last 10 messages for that conversation are retrieved and provided to the agent.

Messages are stored in reverse-chronological order and fetched in chronological order for context, so the agent always sees the natural flow of the conversation.

DetailValue
History depthLast 10 messages per conversation
Direction labels[INBOUND] / [OUTBOUND]
RetentionIndefinite (not cleared on disconnect)
ScopePer phone number pair (your ACS number + remote number)

Health Monitoring​

A daily health check timer runs at 4:00 AM UTC and validates every active ACS connection across all tenants.

For each connection:

  • The encrypted connection string is decrypted and validated by constructing an SMS client
  • If validation fails, the connection status changes to error with a truncated error message stored for admin review
  • If a previously errored connection now validates successfully, the status is restored to active and the error message is cleared

Connection Status Values​

StatusMeaning
activeConnection is healthy and processing messages
errorConnection string validation failed during health check. Check for expired or revoked credentials.
disconnectedSoft-deleted. Credentials cleared, row retained for audit.

To check your connection status, navigate to Capabilities > Connections > ACS SMS. The status badge is shown prominently on the connection page.

Security​

  • AES-256-CBC encryption - Connection strings are encrypted at rest using your tenant's encryption key. Encrypted values are never returned in API responses or written to logs.
  • Credentials cleared on disconnect - When you disconnect, the encrypted connection string is immediately overwritten with [CLEARED]. No sensitive credential data is retained.
  • Tenant isolation - Connections, tools, and message history are strictly scoped to your tenant via TenantId. Cross-tenant data access is not possible.
  • Soft-delete audit trail - Disconnected connections are retained as a record with credentials cleared, so you can see when a connection existed and who created it.
  • Per-connection webhook secret - Event Grid cannot send auth headers, so /api/webhooks/acs/sms stays an anonymous route, but every delivery must still carry a secret in its URL's ?sig= parameter. Each connection is issued its own secret at connect time (or at rotation); the platform stores only its hash, never the plaintext. An event for an unregistered phone number, or carrying a missing or wrong sig, is refused with 401 rather than processed - Event Grid does not retry a 401, so a stale or mistyped webhook URL fails fast instead of silently dropping messages. A connection created before this secret model shipped keeps accepting the shared platform secret until you rotate it onto its own.
  • Message deduplication - Duplicate deliveries from Event Grid are detected and discarded before reaching the agent, preventing repeated processing of the same message.

Rotating the Webhook Secret​

If a webhook URL may have leaked, or you simply lost the one-time copy, click Rotate webhook secret on the ACS SMS connection page. This mints a new secret, invalidates the old URL immediately, and shows the new full URL once. Update the Endpoint on the Azure Portal's Event Grid subscription (Step 3b above) with the new URL right away - events signed with the old secret will be refused.

Troubleshooting​

Connection String Validation Fails​

Problem: The connection string is rejected when connecting

Solutions:

  1. Copy the full connection string from the Azure Portal - it should start with endpoint=https:// followed by your resource URL and the access key
  2. Ensure there are no extra spaces or line breaks in the pasted value
  3. Verify the ACS resource is active and not in a suspended state in the Azure Portal
  4. Try the Secondary connection string if the Primary fails

Inbound SMS Not Received​

Problem: Text messages sent to the ACS number do not appear in agent executions

Solutions:

  1. Verify the Event Grid subscription is configured and shows Active status in the Azure Portal (Capabilities > Connections > ACS SMS shows the webhook endpoint; the full URL with its secret is shown only once, so click Rotate webhook secret if you need a new copy)
  2. Confirm the Event Grid subscription includes both the SMS Received and SMS Delivery Report Received event types
  3. Check that the phone number in Control Bridge matches the number you are texting (E.164 format)
  4. Review the Azure Portal's Event Grid subscription delivery failures for error details
  5. Send another test message and check Governance > Activity History > Agent Runs - allow 30 seconds for the queue to process

Agent Returns "Autonomous Sends Not Enabled"​

Problem: Agent cannot send SMS and indicates it cannot send messages

Solutions:

  1. This is the expected behavior when autonomous sends are disabled (the default)
  2. Navigate to Capabilities > Connections > ACS SMS and locate the Safety Controls section
  3. Toggle Allow Autonomous Sends to ON and confirm the dialog
  4. Retry the agent execution
tip

If you want the agent to only receive and process inbound SMS without replying autonomously, leave autonomous sends disabled. The agent will still receive, read, and process every inbound message - it just cannot send a reply without human confirmation.

Agent Not Assigned or Tool Missing​

Problem: The ACS SMS send tool does not appear when editing an agent, or inbound SMS routes to no agent

Solutions:

  1. Navigate to Capabilities > Connections > ACS SMS and verify an agent is assigned
  2. If no agent is assigned, click Update Settings to select one
  3. The tool is created automatically at connection time - if it is missing, disconnect and reconnect to recreate it
  4. Check that the assigned agent is active and not deleted in Workforce > Agents > Agents & SMEs

Connection Status Shows "Error"​

Problem: The connection status changed to error after working previously

Solutions:

  1. Your ACS connection string may have been regenerated in the Azure Portal (rotating keys invalidates the old string)
  2. Navigate to Capabilities > Connections > ACS SMS and click Update Settings
  3. Paste the new connection string from the Azure Portal
  4. After saving, the status returns to active

Phone Number Format Rejected​

Problem: The phone number is rejected during connection setup

Solutions:

  1. Phone numbers must be in E.164 format: + followed by country code and number, no spaces or dashes (e.g., +15551234567)
  2. Verify the number exists in your ACS resource under Phone Numbers in the Azure Portal
  3. US numbers require +1 prefix followed by the 10-digit number