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.

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 send_sms_acs tool).

Unlike the Twilio integration, which bundles seven tools for messaging, phone intelligence, and account management, the ACS integration is purpose-built for bidirectional SMS. It provides one focused tool (send_sms_acs) 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|       | send_sms_acs        |       | 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. Pro Plus+ Subscription - The ACS SMS integration requires the custom.acs_sms feature code on your subscription
  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 Build > Connections > ACS SMS
  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. A send_sms_acs 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​

The webhook endpoint for inbound SMS is:

https://{your-region}.outermind.ai/api/webhooks/acs/sms

Your region URL is shown on the ACS SMS connection page in Control Bridge.

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 only SMS Received (Microsoft.Communication.SMSReceived)
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 Monitor > Agent Executions in Control Bridge 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 Build > 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 Build > 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 send_sms_acs 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 Build > 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 send_sms_acs 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 will be silently dropped (the webhook will log a warning and discard events for unrecognized phone numbers).

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 send_sms_acs 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

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 send_sms_acs 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)

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 Build > 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.
  • Anonymous webhook endpoint - The /api/webhooks/acs/sms endpoint is intentionally unauthenticated (required by Event Grid), but it only accepts events for registered phone numbers. Unrecognized numbers are logged and discarded.
  • Message deduplication - Duplicate deliveries from Event Grid are detected and discarded before reaching the agent, preventing repeated processing of the same message.

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 (Build > Connections > ACS SMS shows your webhook URL)
  2. Confirm the Event Grid subscription is filtering for SMS Received events only
  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 Monitor > Agent Executions - 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 Build > 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 send_sms_acs tool does not appear when editing an agent, or inbound SMS routes to no agent

Solutions:

  1. Navigate to Build > 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 Build > AI Agents > Agents

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 Build > 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