Skip to main content
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. 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 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.