Skip to main content
After this guide, end users can text a phone number your organization owns and get answers from your agent, and your code can text them first. The number is bought and managed from lua channels; it always carries voice as well, so the same setup is the first half of Voice calls. Verified against lua-cli 3.33.0. Before you begin
  • A project created with lua init, signed in with lua auth configure, with orgId in its project config.
  • A voice defined with defineVoice, registered on LuaAgent.voices, and pushed with lua push voice. Binding a number refuses to proceed without one, because every number answers calls too.
  • For a US number: the legal entity, EIN, address, and opt-in details your carrier registration needs.
1

Terminal: purchase an SMS-capable number

Open the channel menu and choose Manage phone numbers, then Purchase a number. Answer Y to Allow customers to text this number too? (otherwise voice-only); N buys a voice-only number that never receives SMS.
The purchase flow asks for a country (ISO code, default US) and an optional digit pattern, lists up to 50 numbers with country, type, and modality (voice + SMS or voice only), and confirms with charges may apply before buying. The separate Search available numbers item also shows monthly cost. Modality is fixed at purchase.
2

Terminal: bind the number to your agent

After the purchase the menu offers Bind <number> to agent <agentId> now? and asks which voice answers inbound calls. Accept, or come back later with Bind a number to this agent.A number belongs to one agent at a time; binding it elsewhere fails with Phone number <n> is already bound to agent <id>. Unbind it from that agent first. Unbinding keeps the number in the organization; Release a number gives it up for good.
3

Optional: Register a US number for messaging

US carriers require a registered identity behind application traffic. Registration is done over the REST API or in the admin dashboard ; there is no CLI command.
Register a brand with POST /developer/orgs/<orgId>/10dlc/brand: entity_type (SOLE_PROPRIETOR, PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, or GOVERNMENT), display_name, company_name, ein, vertical, phone, email, and a postal address. Sole proprietors add first_name, last_name, and mobile_phone; public companies add stock_symbol, stock_exchange, and verification_email. Then register a campaign with POST …/10dlc/campaign: usecase (for example CUSTOMER_CARE), a description, one to five sample messages, the opt-in, opt-out, and help messages, message_flow_details with pricing_disclosure: true, and tc_agreed: true. Link the number with POST …/phone-numbers/<msisdn>/10dlc/link (digits only, no +), passing campaignId when the organization has more than one campaign; the response lists non-blocking warnings.Brand status is UNVERIFIED, VERIFIED, VETTED_VERIFIED, ACTIVE, INACTIVE, SUSPENDED, or DELETED; campaign status is ACTIVE, EXPIRED, DEACTIVATED, SUSPENDED, or DELETED. POST …/10dlc/brand/sync and …/campaign/sync refresh them from the registry.
Creating a brand, campaign, or toll-free registration and linking a number need the telephony:provision scope; editing a record or submitting a draft with PATCH needs telephony:write, and unlinking needs telephony:manage.
4

Verify

Text the number from your phone. The reply is the agent’s answer, prefixed with the registered brand name and followed by Reply STOP to opt out, HELP for help. and, on US numbers, Msg & data rates may apply. Msg frequency varies. Both are added once, even if the model wrote them itself. Confirm the turn with lua logs --type agent_response.

​
Channel behavior

An opted-out subscriber’s texts are dropped without a reply, and Channels.send to them throws Recipient has opted out of SMS from this sender. Opt-out is per campaign when the number is linked to one, otherwise per number. Every inbound text records a last interaction, so user.send(…) can reach the end user over SMS later; see Send proactive messages.

​
Limits

​
Troubleshooting

Binding needs an active voice because the number also takes calls. Add a defineVoice voice to LuaAgent.voices, run lua push voice, then rerun lua channels.
The phone channel Channels.send resolved has no number on it. When no number is bound at all, the error is Cannot send to sms without an existing conversation instead. Bind a number bought with texting allowed; a voice-only number is attempted and rejected by the carrier, not by this check.
No 10DLC brand, toll-free registration, or fallback brand name resolved for the sending number. Finish the registration, or set the fallback brand name in the admin dashboard .

​
Next steps

Voice calls

Answer and place calls on the same number.

Send proactive messages

Reach end users first over SMS and other channels.

About channels

Inbound and outbound channel vocabularies.

Channels reference

Channels.send parameters and delivery status.