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. Add a friendly name so operators can recognize the sender.
  4. Configure the inbound webhook or fallback URL.
  5. Complete registration and compliance steps before live traffic.

Sender states

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

If the messaging provider buys a line but inbound webhook configuration fails, Textree keeps the number in pending so operators can fix routing before relying on inbound 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 Textree, but your external application will not receive the event until an endpoint is configured.