> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone messaging

> Connect a supported messaging provider and phone number.

Give an agent an SMS-capable number so people can text it. The current connector
supports Twilio and Telnyx, receives text messages and sends plain-text replies.
Voice and media attachment reading are not implemented.

## Connect a number

1. Obtain an SMS-capable number and provider credentials for the agent's account.
2. In agent setup or its connections page, choose **Phone** and the provider.
3. Supply Twilio's Account SID and Auth Token, or Telnyx's API key and webhook
   public key. Formation lists eligible numbers so you can select one.
4. Choose the allowed sender numbers in E.164 format, such as `+15551234567`.
   An empty allowlist admits nobody. **Allow anyone** explicitly opens the number.
5. Save and test from an allowed phone. Formation configures the inbound webhook using
   `PUBLIC_URL`, so the deployment must be publicly reachable over HTTPS.

For Telnyx, configuring a messaging profile's webhook affects every number in
that profile. Use the intended profile and verify the other numbers it serves.
Provider and carrier registration requirements remain your responsibility;
connecting a number does not prove that outbound SMS will be delivered.

## Account ownership and existing instance accounts

Use an agent-owned external account for new configuration, consistent with
Formation's [identity model](https://docs.formation.texturehq.com/runtime/tools.md#identity-and-permissions).

The current code also retains an instance-phone-account flow under **Settings →
Phone numbers**. When configured, the UI can use an existing number or purchase
one on that account. Those connectors reference the instance credential and
resolve it on registry reload; rotation affects all numbers using it. Formation
refuses removal or replacement that would strand connected numbers.

This existing shared-account mechanism does not provide distinct provider-account
identities per agent. A different number or separate connector row does not make
it an agent-owned external account. The ownership rule should not be read as a
claim that these older phone paths enforce it. Purchasing a number incurs a
provider charge; a save failure after purchase must be reconciled before buying
again.

## Who can message the agent

The sender allowlist is enforced before graph persistence or model execution.
Blocked senders receive the provider's normal success acknowledgement, without
an agent reply. Change it through the connection settings or
`PUT /api/agents/{slug}/connectors/{id}/phone-settings`.

The connector ignores delivery/status callbacks, messages addressed to another
number, self echoes, unsupported sender addresses and media-only messages.
Carrier opt-out keywords are acknowledged without an agent reply. Provider-side
opt-out enforcement remains separate.

Each `(agent number, sender number)` pair forms a direct conversation. The
sender's normalized number identifies the participant until a name is learned.
[Identity linking](https://docs.formation.texturehq.com/runtime/identity-linking.md) can verify a relationship to an
account on another connector; merely recognizing a number does not merge people.

## Authentication and replies

The inbound route is `/phone/sms/{digits}`. Formation looks up the owning number and
then verifies the provider's signature. Twilio signs the public URL and form
parameters; Formation reconstructs the URL using `PUBLIC_URL`. Telnyx uses its
Ed25519 signature and timestamp. Unknown routes and failed verification receive
an opaque `401`.

Replies are rendered as plain text with URLs preserved and split to fit SMS
segment limits. Long replies can produce several billed messages. The prompt
includes the medium's constraints; there is no second model rewrite after the
reply is recorded. The connector is reply-only and exposes no arbitrary
outbound-initiation tool. SMS has no lifecycle reaction surface.

## Check delivery health

A connector marked active means its inbound configuration is saved; it is not a
delivery receipt. The dashboard's SMS health check is separate and can be rerun
with **Check again**. It never sends a test text.

For Twilio, the check examines this number's SMS capability and applicable
Messaging Service/campaign information, plus recent outbound delivery evidence.
Only a delivered message within seven days gets **SMS delivered**. Queued or sent
messages do not establish delivery. An approved campaign alone does not prove
that this particular number has completed registration.

Missing registration can be shown as a problem; pending, unsupported, failed or
timed-out checks remain **SMS unverified**. Health is historical evidence, not a
guarantee about the next recipient. The endpoint returns no message body,
recipient number or credential.

Implementation: [`internal/connector/phone`](https://github.com/TextureHQ/formation/tree/main/internal/connector/phone).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.