STACK
MENU
DOCS / THE ACCOUNT / PHONE NUMBER AND TEXTS

Phone number and texts

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.

Choose the number

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.

typescript
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' }
  • Numbers are US or Canadian. A toll-free number is US only.
  • A local number is bought after your first top-up. Until then the piece waits. A toll-free number needs no top-up first.
  • Every number receives texts and calls as soon as it is issued.

Get a toll-free number approved for texting

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:

bash
npx @getstackrun/cli account toll-free acct_123 submit --file ./verification.json

# Read where it stands.
npx @getstackrun/cli account toll-free acct_123
  • The file holds the business name, website, type and address, a contact, the use case with a sample message, how people opt in (with one to five https links to pages or images that show it), the expected volume, an email address for the outcome, and links to your privacy policy and terms.
  • A business that is not a sole proprietor also gives its registration number.
  • Submitting needs a person's approval. The command waits for it.
  • The tools are stack_submit_account_toll_free_verification and stack_get_account_toll_free_verification.

A 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.

Send a text

prompt
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:

typescript
await stack.accounts.sendSms('acct_123', {
  to: '+14155550123',
  body: 'Your order has shipped.',
});
bash
npx @getstackrun/cli account send-sms acct_123 --to +14155550123 --body "Your order has shipped."
  • to is one number in international form, starting with +.
  • A text is at most 1,600 characters.
  • One text is one action, and it is charged at the carrier's price for the destination.
  • Any agent of yours can text from the number, unless you set it to read only: see Email. It sends under its own Passport.
  • STACK sets no hours and no daily limit. Consent and the time of day are yours to keep.

Read texts

prompt
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.

The do-not-contact list

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.

  • stack_list_opt_outs and stack_add_opt_out read the list and add a number. An agent can do both.
  • Only the owner or an admin can take a number off: stack_remove_opt_out, or account opt-out-remove <id>.
  • From code: stack.accounts.optOuts.list(), .add(number) and .remove(id).

Add a number to an account that has none

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.

When a text is refused

  • 403 MESSAGES_READ_ONLY - you set this agent to read only. It cannot send.
  • 403 TOLL_FREE_VERIFICATION_REQUIRED - the toll-free number is not verified yet. The answer carries the status.
  • 403 US_CARRIER_REGISTRATION_REQUIRED - the US local number is not registered with the carriers.
  • 403 RECIPIENT_OPTED_OUT - the number is on the do-not-contact list.
  • 422 DESTINATION_NOT_AVAILABLE - the carrier has no price for the destination, or refuses it.
  • 409 ACCOUNT_PIECE_NOT_READY - the number is not issued yet, for example it waits for the first top-up.
  • 402 INSUFFICIENT_BALANCE - the credit cannot cover the text.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as sms.send.
  • A paused number sends nothing. The owner lifts the pause with stack_resume_account_piece.

Reference

Every field is on Messages, Mail and Texts. Every tool is in the tool reference. For voice, see Calls.

Phone number and texts | Docs