# Numbers

Canonical URL: https://texttree.ai/en/docs/numbers/
Markdown URL: https://texttree.ai/en/docs/numbers.md
Page type: docs
Translation status: approved
Legal status: not_required

## Summary

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

## Source content

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

```json
{
  "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.