> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.
# SMS
> Prepare a Twilio number for SMS, track messaging registrations, and connect it to a Distribution Ion.
SMS onboarding is in preview and requires environment-specific database and provider validation before deployment.
The implementation includes toll-free verification, initial US local-number Brand/Campaign forms, draft resume,
supported same-Campaign corrections, and sender enrollment. Optional Brand appeals and extra vetting remain deferred.
This guide does not assert that a particular environment has passed acceptance.
An **SMS Distribution Ion** connects a reserved Twilio number to an
[Ion Sequence](/docs/concepts/ions#ions-and-sequences). Owning a number is separate from permission to send SMS.
An existing [Telecom Voice](/docs/distributions/voice/telecom) number may be reused when it is eligible for SMS.
## Overview
Open **Integrations → SMS** to manage numbers and messaging registrations. The **Registrations** tab brings three
different provider resources into one list:
| Registration | Scope | Purpose |
| - | - | - |
| Toll-free SMS verification | One toll-free number | Obtain permission to send SMS from that number. |
| Business registration (Brand) | A business in the organization | Establish business and identity verification. |
| Campaign registration | A use case and its enrolled numbers | Register messages sent under an approved Brand. |
Toll-free verification is not Brand registration. A US local number needs both an eligible, approved Brand and an
approved Campaign, followed by successful enrollment of that particular number. Campaign membership alone is not
confirmation that a carrier has enrolled the number.
## Default request loop
1. Twilio delivers an incoming message to Aion.
2. Aion records the receipt and routes eligible work through the Distribution's Sequence.
3. Before invoking the agent, Aion checks the current number, messaging registration, and credit policy.
4. The final response is prepared for delivery back into the originating conversation.
5. Aion checks readiness again before sending, since approval or account availability may have changed.
A registration failure rejects the SMS request with an identifiable A2A error code and a reason. It does not grant
permission to send an explanatory SMS from an unapproved number. Accepted input and provider delivery are separate
events; a successful agent response does not itself prove external delivery.
## Configuration
### Choose or reserve a number
1. Open **Integrations → SMS → Numbers**.
2. Reuse an eligible number or select **Reserve SMS number** and review the displayed reservation charge.
3. Choose a US local or supported North American toll-free SMS number. Other countries and unknown types are ineligible.
4. Keep the Distribution inactive while its registration is missing, pending, or rejected.
There is no Aion organization-wide one-number cap. Each additional reservation has its own charges, and Twilio's
inventory, account, and registration limits still apply. Reusing one number for Voice and SMS does not reserve a
second copy of it. Releasing that number can affect both channels.
### Toll-free SMS verification
This application concerns **outbound SMS for one number**. Reserving a toll-free number, receiving calls, or using
Voice does not establish messaging approval.
1. On **Registrations**, select **Add registration → Toll-free SMS verification**.
2. Choose the reserved number and open its detail screen.
3. Select **Start verification form** or the available resume action.
4. Complete Twilio's embedded form inside Aion, then submit it.
5. Return to the detail screen to track the status recorded by Aion.
Prepare business and contact details, your messaging purpose, representative message samples, and evidence showing
how recipients consent. Supply public privacy-policy and terms URLs when the form requires them; Aion does not
create or host those materials for you. See
[Twilio's toll-free requirements](https://www.twilio.com/docs/messaging/compliance/toll-free/console-onboarding)
for the provider's current instructions.
| Displayed state | Meaning and next step |
| - | - |
| SMS messaging not activated | Start a form, or resume its saved draft. |
| Pending review | The application was submitted; wait for the provider's decision. |
| SMS messaging approved | Registration passed; other number and credit checks still apply. |
| SMS messaging rejected | Read the failure information and correct the form if the provider permits it. |
Completing or closing the embedded form is not approval. Aion uses backend provider observations, not browser
completion callbacks, to determine status. Pending screens refresh periodically while visible and when you return.
Aion also checks open toll-free, Brand and Campaign registrations periodically to recover missed status events.
These status reads do not create applications or charges, and do not guarantee instant visibility or review deadlines.
If Aion cannot confirm submission, use **Retry submission recording** or **Refresh status**. That warning does not mean
Twilio rejected the application. Expired form sessions can be reopened with fresh temporary credentials. Rejected
applications are editable only when the provider allows it; a correction deadline may apply.
### Business registration (Brand)
A Brand represents the business sending messages. It belongs to the organization's Twilio account scope, not to an
individual number. An Aion organization is not limited to one Brand; provide the business information Twilio requires
for each registration.
1. Select **Add registration → Business registration (Brand) → Continue to Brand setup**.
2. Enter a display name and choose **Standard business** or **Sole Proprietor**.
3. Select **Start registration form**, then complete Twilio's embedded questionnaire.
4. Return to the retained registration to inspect business and identity status separately.
Opening the setup page does not submit an application. The explicit Start action opens the provider session after
authorization and credit checks. Existing unsubmitted drafts offer **Resume registration form** without starting a
new application. A browser submission or completion callback is not approval.
If a retained Brand or Campaign draft says its initialization is unconfirmed, contact support before starting
another form.
An interrupted initialization may have created a provider inquiry whose identifier Aion did not retain. The periodic
status monitor cannot safely recreate that resource. Support must investigate and recover the existing correlation,
or establish that no resource was created, before another attempt.
Standard and Low-Volume Standard registrations cover applicable businesses with tax identifiers. Sole Proprietor
registration is a variant of the Brand flow for eligible individuals without one, not a fourth registration program.
It includes mobile identity confirmation using an eligible personal mobile number, not a Twilio-provisioned number.
A Sole Proprietor Brand supports one Campaign, which supports one sender. Choose the classification that
matches the provider's eligibility rules; do not select Sole Proprietor simply to avoid business verification.
Brand approval and identity verification are separate prerequisites. Follow the form's required identity action before
continuing to Campaign registration. See
[Twilio's business registration guide](https://www.twilio.com/docs/messaging/compliance/a2p-10dlc)
and [Sole Proprietor onboarding][sole-proprietor-guide].
[sole-proprietor-guide]: https://www.twilio.com/docs/messaging/compliance/a2p-10dlc/onboarding-isv-api-sole-prop-new
### Campaign registration
A Campaign describes a messaging use case under an approved Brand. Prepare a use-case description, sample messages,
the opt-in process, and required public policy links. A Standard Campaign may serve multiple enrolled numbers.
Sole Proprietor Campaigns allow one sender. One number can belong to only one Campaign at a time, so changing its
assignment must not be treated as a second simultaneous membership.
Select **Add registration → Campaign registration → Continue to Campaign setup**, choose an approved Brand with
completed identity verification, enter a display name, then select **Start registration form**. The server rechecks
the prerequisites. After approval, use **Add number** on the Campaign detail screen to associate one eligible reserved
number at a time. This reuses the existing number; it does not reserve another one.
After Campaign approval, each number must complete enrollment. Replacing a sender can involve removal from the old
Campaign and new enrollment; do not assume that an association change instantly enables sending. Remove the old
association and wait for deregistration before assigning the number elsewhere. Aion requires carrier enrollment
events; Messaging Service membership is not enrollment proof. Periodic Brand/Campaign reads cannot recover a missing
number-enrollment event because an authoritative carrier-status lookup has not been verified.
Removing a number, deleting its Distribution, or leaving a Campaign empty is not the same as canceling the Campaign.
**Delete Campaign** is a separate action with a confirmation explaining the affected numbers and sending entitlement.
Acceptance queues durable work; it does not mean the provider already deleted the Campaign. Empty Campaigns can be
retained for reuse and can continue incurring recurring fees until provider cancellation succeeds. This action does
not delete the Brand, release phone numbers or close the organization.
#### Correct a rejected Campaign
The detail screen shows provider review notes, individual error codes, explanations, and affected fields when supplied.
These explanations are also retained in the Campaign's document history. If the rejection permits a supported field
correction, a billing manager can select **Correct and resubmit Campaign** to reopen the existing registration.
Aion rechecks the current provider state before opening the form; submission still requires provider review.
Aion currently assumes no additional vetting fee for correcting the **same Campaign**. Its original registration fee
is not waived. Creating a replacement Campaign is a separate application that can incur new fees. Unknown, prohibited,
or unsupported rejection reasons do not unlock correction automatically; follow the explanation and contact support.
Optional Brand appeals and extra vetting are not available here; they may need manual support or a future workflow.
### Activate a Distribution
In [Composer](/docs/composer), select the SMS Distribution Ion and open **Identity**. Choose the eligible reserved
number or reserve a new one. Follow **Manage SMS registration** to the form's detail page; the editor does not open a
second embed. The selection identifies the number's service identity, not its reservation record.
Once the number is ready, open **Info**, activate the Distribution, and sync the Project. Missing, pending, rejected,
or unavailable registrations block activation and outbound replies. An inactive Distribution can retain an unapproved
number while onboarding proceeds. Losing approval does not prevent deactivation.
Use **Refresh readiness** after an external status change. If previously saved validation errors remain, explicitly
sync the Project to revalidate it, even if there are no pending changes. Sync also submits any staged changes, so
review those first. Do not replace or reselect the number merely to bypass an error.
### Permissions and notification contact
Organization read permission allows viewing registration progress. Organization billing-management permission is
required for provisioning, starting/resuming forms, changing sender associations and deleting Campaigns. The authorized
logged-in user's email is used when the provider initializer accepts a notification contact; it does not create a
separate organization contact setting.
### Fees and retained Campaigns
Aion passes provider charges to the owning organization. Number reservation and holding charges are separate from
message/carrier usage and local-number registration costs. Review the price displayed before confirming a reservation.
SMS usage is attributed to its originating Distribution and agent when that association is known.
Registration forms open directly from their detail/setup screen; there is no intermediate Aion pricing-consent modal.
A separate pricing-catalog tab is planned and is not part of this preview. This does not waive charges or bypass
credit checks. A provider can charge for an unsuccessful application or a repeated billable attempt. Unverified paid
resubmission paths remain unavailable; supported same-Campaign corrections follow the policy above.
Amounts and rules can change; see
[Twilio's A2P pricing](https://www.twilio.com/en-us/messaging/pricing/us).
Suspending message traffic does not itself cancel recurring Campaign charges. Retaining an empty Campaign can still
incur fees; removing its last number is not a cancellation request.
Under Aion's **provisional UTC calendar**, the first approval covers that calendar month. Each subsequent month incurs
one subscription charge on the first UTC day while the Campaign remains billable, regardless of its number count.
For example, approval on September 30 can be followed by renewal on October 1. This is a working assumption, not a
provider-confirmed billing interval or a promise of 30 days of service.
Aion uses the retained registration fee schedule and markup, attributes the charge to the owning organization and
Campaign, and records each month once through its ordinary usage billing. Delayed processing can capture missed months;
replayed events do not create another initial fee. Confirmed cancellation bounds future periods, but failed cancellation
or exhausted credits alone does not erase charges already incurred. These calculated fees are not itemized Twilio
invoices.
### Month-end Campaign cancellation
Aion uses **first-of-month renewal in UTC as a working assumption**, not as a verified Twilio billing contract.
This is not a provider-reported expiry date or a guarantee of service through a paid period. Actual charge dates can
differ, and cancellation can end service before previously paid time has elapsed. This policy does not promise a
refund or protection against every subsequent charge.
On the **last UTC calendar day of each month**, Aion checks retained Campaigns for organizations whose credit policy
is **Exhausted** or **Suspended**. This includes Campaigns with no enrolled numbers. Healthy or merely low-credit
organizations are not eligible. Cancellation may occur at any point during that day, not just immediately before
midnight, leaving time for ordinary retries.
Before a deletion attempt, Aion checks the current credit policy and the exact Campaign again. It does not initiate
a new automated deletion after that month's window closes. An explicit billing-manager deletion does not wait for
month end or require exhausted credits. Confirmation of an earlier request can still finish afterward.
Provider rejection, restrictions, or an unavailable service can prevent cancellation; a failed attempt does not
mean recurring fees stopped. See [Twilio's Campaign API][campaign-api] and
[its compliance-suspension restriction](https://www.twilio.com/docs/api/errors/21729).
This closes the **Campaign registration**, not the Aion organization or Twilio subaccount. It does not delete the
Brand or release phone numbers. Deletion is not a reversible pause. Restoring credits afterward does not restore
the registration automatically; a new paid application and approval may be necessary.
#### Retained closure history
Open a Campaign from **Integrations → SMS → Registrations** to see its current state and the 50 most recent accepted
document versions. Earlier versions remain in the retained history. Aion records the cancellation reason, observed
credit policy, assumed renewal boundary, decision timestamps, and safe failure or skip codes.
| Cancellation outcome | Meaning |
| - | - |
| Requested | Aion recorded the intended deletion; provider closure is not yet confirmed. |
| Failed | An attempt failed. The Campaign may remain billable. |
| Skipped | Aion did not proceed, for example because credits recovered or the time window elapsed. |
| Confirmed | Aion confirmed the provider Campaign was absent and recorded that observation time. |
The assumed renewal boundary and confirmed closure time are different values. A requested or failed operation is
never shown as a confirmed closure. The registration and its prior versions remain visible after closure, providing
a history of what changed and why rather than removing the local record.
[campaign-api]: https://www.twilio.com/docs/messaging/api/usapptoperson-resource
## Message mapping
Incoming SMS/MMS is normalized into the shared A2A messaging contract; final agent output is converted to a reply using
the recorded conversation target. Frameworks should use the shared
[Distribution/Messaging contract](/a2a/extensions/aion/distribution/messaging/1.0.0), rather than provider account IDs
or registration tokens. Registration status is a delivery prerequisite, not an extra agent-response payload schema.
## Features
This guide covers number entitlement, registration, and response readiness. It does not promise chat-style streaming,
reactions, cards, or transcription. SMS, attachment metadata, accessible MMS content, and voice transcription are
distinct capabilities; see [Media and attachments](/docs/distributions/messaging/media-and-attachments) before assuming
that support for one implies another.