Tipo de página: docs
API para desarrolladores
Contratos de envío de mensajes y de estado para la API alfa actual de TextTree.
Respuesta directa
Contratos de envío de mensajes y de estado para la API alfa actual de TextTree.
Contenido de la página
# API para desarrolladores
La API JSON actual es intencionalmente acotada. Está enfocada en una ruta crítica de producción:
encolar SMS salientes y verificar su estado.
## URL base
El desarrollo local con Phoenix se ejecuta en `http://localhost:4001`.
Todos los endpoints para desarrolladores documentados viven bajo `/api/v1`.
## Autenticación
Las llamadas autenticadas a la API requieren un token de acceso bearer `txt_...` emitido por TextTree.
El mismo modelo de identidad local se usa para la app de navegador, la API para desarrolladores y
las rutas MCP. Las claves de API heredadas `txk_...` se conservan como registros internos y no
son aceptadas por `/api/v1/messages`.
```http
Authorization: Bearer <textree_access_token>
Accept: application/json
```
`POST /api/v1/messages` requiere `messages:write`. Los endpoints de inventario de números
requieren `numbers:read` o `numbers:write`. Las identidades de correo electrónico, Google,
billetera y agente se normalizan en la misma identidad local de TextTree antes de la
autorización.
## Arranque de cuenta headless
Los clientes de IA y de API pueden crear una cuenta sin correo electrónico, OAuth de Google ni
autenticación con billetera usando el arranque con nombre de usuario y contraseña.
`POST /api/v1/accounts`
Esta ruta es pública, solo JSON, y está limitada a una creación de cuenta exitosa
por dirección IP cada cinco minutos. TextTree almacena un hash de la dirección IP para
el registro de limitación; la IP en bruto no se almacena.
### Cuerpo de la solicitud
```json
{
"username": "agent-demo",
"password": "correct horse battery staple"
}
```
### Respuesta exitosa
```json
{
"account": {
"id": "9d7d9df7-58a0-4716-b82e-7ad5e73f7b36",
"username": "agent-demo"
},
"backup_codes": ["AAAA-BBBB-CCCC-DDDD"],
"token": {
"type": "Bearer",
"access_token": "txt_...",
"scopes": ["mcp:read", "mcp:execute", "messages:write"],
"expires_at": "2026-06-03T15:30:00Z"
}
}
```
Guarda el token bearer `txt_...` y los códigos de respaldo de inmediato. El correo electrónico
sintético interno, el hash del token, la contraseña y el hash de IP de limitación nunca se devuelven.
### Errores
- `422` con `{"error":"validation_failed","details":...}` para nombres de usuario inválidos o duplicados
o contraseñas inválidas
- `429` con `{"error":"account_creation_rate_limited","retry_after_seconds":...}` cuando la
IP del solicitante ya creó una cuenta en los últimos cinco minutos
## Salud
`GET /api/v1/health`
Esta ruta es pública y es útil para verificaciones de despliegue y pruebas rápidas locales.
## Encolar un mensaje saliente
`POST /api/v1/messages`
### Cuerpo de la solicitud
```json
{
"phone_number": "+15551234567",
"body": "Your verification code is 482019",
"estimated_cost_cents": 2,
"idempotency_key": "msg_2026_04_26_0001",
"metadata": {
"campaign": "alpha-invite",
"source": "api"
}
}
```
### Campos
- `phone_number`: número de teléfono del destinatario en formato E.164, requerido
- `body`: cadena requerida, de 1 a 1600 caracteres
- `estimated_cost_cents`: entero positivo opcional, por defecto el costo de SMS configurado
- `idempotency_key`: cadena opcional, de 8 a 128 caracteres, con alcance por usuario
- `metadata`: objeto JSON opcional
`phone_number` es el campo de destinatario de la V1. No envíes `to` a menos que una versión futura de la API lo documente explícitamente.
Los envíos por API usan selección automática de remitente. Los envíos desde la app de navegador pueden
elegir un número de marca conectado; ese remitente seleccionado pasa a formar parte de la
solicitud de mensaje idempotente.
### curl
```bash
curl https://api.texttree.ai/api/v1/messages \
-H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+15551234567",
"body": "Your verification code is 482019",
"idempotency_key": "msg_2026_04_26_0001"
}'
```
### Respuestas exitosas
Los mensajes recién encolados devuelven `202 Accepted`:
```json
{
"message": {
"id": "8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb",
"status": "queued",
"phone_number": "+15551234567",
"body": "Your verification code is 482019",
"provider": "messaging_provider",
"consent_status": "missing",
"external_id": null,
"estimated_cost_cents": 2,
"idempotency_key": "msg_2026_04_26_0001",
"metadata": {
"campaign": "alpha-invite",
"source": "api"
},
"inserted_at": "2026-04-26T20:44:12Z",
"updated_at": "2026-04-26T20:44:12Z",
"links": {
"self": "/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb"
}
},
"replayed": false
}
```
Si el mismo usuario reproduce la misma `idempotency_key` con el mismo payload de mensaje
y la misma selección de remitente, TextTree devuelve `200 OK` con el mensaje existente
y `"replayed": true`.
### Respuestas de error
- `422` con `{"error":"validation_failed","details":...}` cuando el cuerpo está mal formado
- `403` con `{"error":"workspace_suppressed"}` cuando el destinatario está bloqueado por una supresión del workspace
- `402` con `{"error":"spend_limit_exceeded"}` cuando se excedería el límite de gasto actual
- `409` con `{"error":"idempotency_conflict"}` cuando una clave de idempotencia se reutiliza con un
destinatario, cuerpo, costo o remitente diferente
- `422` o detalles de falla vinculados al proveedor cuando un remitente de app seleccionado ya no
está disponible para el workspace
## Consultar el estado de un mensaje
`GET /api/v1/messages/:id`
Esto devuelve la misma envoltura `message` usada en las respuestas de creación.
El ciclo de vida actual del estado de un mensaje es:
- `queued`
- `dispatching`
- `sent`
- `delivered`
- `failed`
- `blocked`
`external_id` se completa una vez que la ejecución orientada al proveedor tiene un identificador de proveedor estable.
### Ejemplo de estado
```bash
curl https://api.texttree.ai/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb \
-H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```
```json
{
"message": {
"id": "8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb",
"status": "delivered",
"phone_number": "+15551234567",
"estimated_cost_cents": 2,
"links": {
"self": "/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb"
}
}
}
```
## Antes de enviar
La creación de cuentas es autoarrancable mediante `POST /api/v1/accounts` y
`POST /mcp/accounts`, pero el envío saliente aún requiere configurar el workspace.
Antes de que `POST /api/v1/messages` pueda tener éxito en un workspace nuevo, quien llama o
el operador debe:
- autenticarse a través de TextTree e incluir un token con `messages:write`
- confirmar que el destinatario no esté bajo una supresión activa del workspace
- establecer un límite de gasto activo en `/app`
- configurar un remitente de prueba, un número de remitente en vivo o el modo de remitente automático
## API de números
`GET /api/v1/numbers` requiere `numbers:read`.
`POST /api/v1/numbers` requiere `numbers:write` y compra un número a través del
límite del proveedor de mensajería de TextTree. Incluye un `area_code` cuando el
operador quiere un número local. Las compras en vivo permanecen bloqueadas a menos que el despliegue
habilite explícitamente la barrera de protección de compra de números en vivo.
```bash
curl https://api.texttree.ai/api/v1/numbers \
-H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"area_code": "415",
"friendly_name": "Support line"
}'
```
Las compras exitosas devuelven `201 Created`:
```json
{
"number": {
"id": "b86fbe4d-2b92-4664-8e91-d2ed1d37f827",
"number": "+14155550123",
"friendly_name": "Support line",
"capabilities": ["sms"],
"status": "connected",
"inbound_webhook_url": "https://app.texttree.ai/webhooks/provider/incoming",
"compliance_status": "pending"
},
"webhook_configured": false,
"warning": "provider_inbound_webhook_configuration_api_not_documented"
}
```
## Límites actuales de la fase alfa
La API para desarrolladores **no** expone actualmente:
- endpoints CRUD heredados de metadatos de consentimiento/contactos
- endpoints CRUD de supresiones de workspace
- endpoints CRUD de límites de gasto
- creación directa de sesiones de financiamiento; usa las facturas de financiamiento de onboarding para las recargas de lanzamiento