How an agent gets a phone number, how you get it approved for texting, and how the agent sends and reads texts. What the number is and what it costs is on Services. Calls have their own guide.
The number is chosen when the account is opened, and cannot be changed afterwards. Without a choice, a US account gets a toll-free number.
await stack.accounts.open(
{ name: 'assistant', phone: { country: 'US' } }, // toll-free
{ idempotencyKey: 'open-assistant-1' },
);
// A local number instead:
// phone: { country: 'US', area_code: '415' }
// phone: { country: 'CA', area_code: '416' }A US toll-free number sends texts only after the carriers have verified your business. The owner or an admin submits the details once, from a file:
npx @getstackrun/cli account toll-free acct_123 submit --file ./verification.json
# Read where it stands.
npx @getstackrun/cli account toll-free acct_123A Canadian local number can text at once. A US local number needs carrier registration before it can text. That registration cannot be done through STACK yet, so a US local number receives texts and calls and places calls, and a text from it is refused with 403 US_CARRIER_REGISTRATION_REQUIRED. To text US numbers, use a toll-free number.
Text +1 415 555 0123 from the assistant account: your order has shipped.The client calls stack_send_account_sms. From code or the terminal:
await stack.accounts.sendSms('acct_123', {
to: '+14155550123',
body: 'Your order has shipped.',
});npx @getstackrun/cli account send-sms acct_123 --to +14155550123 --body "Your order has shipped."What texts has the assistant account received?The client calls stack_list_account_messages with channel: "sms". From code: stack.accounts.messages.list('acct_123', { channel: 'sms' }). To start the agent when a text arrives, set a rule: see Wake-ups.
When someone replies STOP, their number goes on the account's do-not-contact list, and texts and calls to it are refused. START takes it off again.
An account opened without a phone number can be given one later with stack_add_account_piece (piece phone, with the same phone options as at open), from code with stack.accounts.addPiece, or in the terminal with account add-piece <id> --piece phone --idempotency-key <key> --file phone.json. Only the owner or an admin can. The checks are those of opening an account with a number, so a number beyond the first still waits for a qualifying top-up.
Every field is on Messages, Mail and Texts. Every tool is in the tool reference. For voice, see Calls.