Documentation

Numbers

Rent, connect, and configure sending and receiving SMS numbers.

Phone numbers define sender identity, inbound routing, compliance status, and messaging capabilities.

Start with a test sender, then register or connect a production sender before switching to Live.

Number record

{
  "id": "num_123",
  "number": "+15557654321",
  "friendly_name": "Support line",
  "capabilities": ["sms", "mms"],
  "status": "active",
  "inbound_webhook_url": "https://example.com/textree/inbound",
  "compliance_status": "approved",
  "created_at": "2026-04-28T14:00:00Z"
}

Setup flow

  1. Open Phone Numbers in the app.
  2. Choose Buy number or Connect existing number.
  3. Enter an area code when buying a local number.
  4. Add a friendly name so operators can recognize the sender.
  5. Add the inbound webhook or fallback URL you want TextTree to use.
  6. Complete registration and compliance steps before live traffic.

Connected branded numbers appear in the app sender selector for dashboard quick-send and the Send page. TextTree validates ownership and connection status before queueing and again before dispatch.

Sender states

  • connected: saved in TextTree and available for configured send paths.
  • pending: waiting for registration, connection, or compliance review.
  • disabled: not available for outbound sends.

If an app send references a branded number that is later disconnected or no longer belongs to the workspace, dispatch fails with sender_number_unavailable instead of using another sender.

The SMS provider does not currently expose a documented inbound webhook configuration API. When TextTree buys a line, API responses return webhook_configured: false with provider_inbound_webhook_configuration_api_not_documented; operators should verify inbound routing before relying on replies.

API setup

The launch API exposes:

  • GET /api/v1/numbers with numbers:read
  • POST /api/v1/numbers with numbers:write

POST /api/v1/numbers accepts area_code, friendly_name, and optional inbound_webhook_url. Live buys remain blocked unless the deployment explicitly enables the live-number-buy guardrail.

Inbound routing

Inbound SMS received on a number can create or update:

  • message logs
  • conversation threads
  • contact history
  • customer webhook deliveries
  • AI handoff state

If an inbound webhook URL is missing, the message is still logged in TextTree, but your external application will not receive the event until an endpoint is configured.