> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/channels/sms.md).

# SMS

The SMS channel lets agents send and receive text messages through provisioned phone numbers. Outbound SMS is sent through a messaging service associated with an SMS use case, which manages sender selection, compliance gating, and delivery tracking automatically. Both SMS (text-only) and MMS (multimedia) messaging are supported through the same send interface - messages can include text content, media attachments, or both.

## Provisioning

SMS provisioning is a regulated, operator-managed process rather than a self-service Platform API or Developer Console flow. It includes the applicable carrier registration, messaging use case, and phone-number configuration. Timing depends on carrier review and number readiness.

After provisioning, the Platform API can list workspace-owned use cases and bind an eligible SMS use case to a service. It does not create the upstream SMS setup, campaign, messaging service, or number assignment for the workspace.

To request SMS provisioning for your workspace, contact your Amigo account team.

### How Use Cases Are Backed

Each provisioned SMS use case is backed by managed messaging infrastructure and an assigned phone-number pool. Sender selection occurs within that use case; callers starting an outbound conversation supply the use case and recipient, not a `From` number.

## Inbound SMS

Customers can text a configured phone number to start a conversation with the agent. The platform routes the message to the bound service, resolves authorized context when available, and runs the agent's reasoning engine. Messages from the same caller on the same use case are serialized onto the current non-terminal durable conversation. Terminal Context Graph completion, closing a known conversation ID, a use-case rebind, or outbound creation with `force_new: true` starts a fresh thread; see [Phone-Keyed Threads](/channels/text-sessions.md#phone-keyed-threads).

Once operator provisioning is complete, the workspace application does not configure a provider webhook for each conversation. The managed channel validates inbound delivery, deduplicates provider retries, resolves the destination use case, and records message metadata for processing and analytics.

When a reply depends on supported background work, the asynchronous channel policy suppresses the intermediate acknowledgement and attempts to re-drive the final reply. Provider acceptance and delivery remain separate; inspect delivery status and recovery evidence rather than assuming the recipient received it. See [Long-Running Tools and Reply Delivery](/channels/email.md#long-running-tools-and-reply-delivery).

Signature validation ensures that only authentic message deliveries are accepted. Duplicate deliveries (from network retries) are silently acknowledged without creating duplicate records.

## Outbound SMS

The platform supports agent-initiated outbound SMS without waiting for an inbound text. The bound service generates the opening turn using its published configuration and the authorized context available at execution time. A recipient reply can continue the resulting durable conversation.

Outbound SMS conversations are started through the conversation lifecycle API by specifying SMS as the channel, a recipient phone number in E.164 format, and a use case that determines the sender. The sender (FROM number) is resolved from the use case configuration - it is never supplied by the caller. See [Outbound](/channels/outbound.md) for details on the channel-generic lifecycle.

Outbound SMS can support reminders and follow-up workflows when the workspace has a provisioned use case and the application supplies the required routing inputs. Contact the Amigo team to confirm availability and onboarding for your workspace.

{% hint style="info" %}
Outbound text conversations support entity-based resolution. When an entity ID is supplied, the runtime can load authorized context available for that entity before the first message rather than relying only on phone-number matching. Missing data, source permissions, and projection lag still apply.
{% endhint %}

## Channel Switching

An active conversation on another channel (such as iMessage) can be switched to SMS, preserving the full conversation history. Each turn records which channel it occurred on, so the history is self-describing across channel changes. See [Outbound](/channels/outbound.md#switching-between-sms-and-imessage) for the switch lifecycle.

## Opt-Out and Opt-In Compliance

The platform enforces A2P SMS opt-out and opt-in compliance for all SMS channels. When a recipient sends a recognized opt-out keyword (such as STOP), the platform records their opt-out preference and stops delivering messages to that number. Recognized opt-in keywords (such as START) reverse a previous opt-out and resume message delivery.

Opt-out and opt-in handling follows industry-standard A2P messaging guidelines. The platform automatically responds to opt-out and opt-in requests with a confirmation message, and compliance state is tracked per recipient number. Agents and campaigns cannot override a recipient's opt-out status - messages to opted-out numbers are suppressed at the channel layer before reaching the delivery provider.

The managed channel persists opt-in and opt-out state and records keyword activity for operational review. Use only the workspace-facing status APIs or support workflow documented for your deployment; provider-management interfaces are not part of the public Platform contract.

## Phone Number Assignment

SMS use cases require phone numbers with SMS capability, and the compliance requirement depends on the number type. Toll-free numbers must complete toll-free verification before they can be assigned. US local and national long-code numbers must have an approved messaging campaign registration before they can be assigned. Both paths keep the number compliant with carrier rules for application-to-person messaging.

Unlike voice channels - where a single phone number can serve different voice use cases on different channels (one for inbound voice, one for outbound voice, one for voicemail) - SMS assignment is exclusive. A phone number can only be assigned to one SMS use case at a time. This mirrors the underlying telephony constraint that a phone number belongs to exactly one messaging service.

## Channel Separation

SMS and voice operate on separate channel bindings. A phone number can be assigned to both a voice use case and an SMS use case simultaneously - the two channels do not conflict. The platform tracks voice and SMS assignments independently, so assigning a number to an SMS use case does not affect any existing voice assignments on that number, and vice versa.

## Lifecycle

The managed SMS lifecycle is:

1. **Provision** - An Amigo operator creates the required channel resources and completes carrier registration.
2. **Assign numbers** - Eligible SMS-capable numbers join the use case after the applicable verification or campaign approval.
3. **Bind service** - The workspace binds the provisioned use case to an eligible service through the Platform API.
4. **Send and receive** - Messages route through the managed number pool and durable conversation path.
5. **Retire** - An operator unassigns numbers and tears down upstream resources when the use case is no longer needed.

{% content-ref url="/pages/F9G0lrxZA31mW1pawkgs" %}
[Text Sessions](/channels/text-sessions.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/channels/sms.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.