Tipo de página: docs
API do desenvolvedor
Envio de mensagens e contratos estaduais para a API alfa TextTree atual.
Resposta direta
Envio de mensagens e contratos estaduais para a API alfa TextTree atual.
Conteúdo fonte
# API para desenvolvedores
A API JSON atual é intencionalmente restrita. Está focado em um caminho crítico de produção:
Coloque SMS de saída na fila e verifique seu status.
## URL base
O desenvolvimento local com Phoenix é executado em `http://localhost:4001`.
Todos os endpoints de desenvolvedor documentados residem em `/api/v1`.
## Autenticação
As chamadas autenticadas para a API requerem um token de acesso ao portador `txt_...` emitido pelo TextTree.
O mesmo modelo de identidade local é usado para o aplicativo do navegador, a API do desenvolvedor e
Rotas MCP. As chaves de API herdadas `txk_...` são mantidas como registros internos e não são
são aceitos por `/api/v1/messages`.
```http
Authorization: Bearer <textree_access_token>
Accept: application/json
```
`POST /api/v1/messages` requer `messages:write`. Pontos finais de inventário numérico
requerem `numbers:read` ou `numbers:write`. Identidades de e-mail, Google,
carteira e agente são normalizados para a mesma identidade TextTree local antes
autorização.
## Inicialização de conta sem cabeça
Os clientes de IA e API podem criar uma conta sem e-mail, Google OAuth ou
autenticação de carteira usando nome de usuário e senha de inicialização.
`POST /api/v1/accounts`
Esta rota é pública, somente JSON, e está limitada à criação bem-sucedida da conta
por endereço IP a cada cinco minutos. TextTree armazena um hash do endereço IP para
o registro de limitação; o IP bruto não é armazenado.
### Corpo da solicitação
```json
{
"username": "agent-demo",
"password": "correct horse battery staple"
}
```
### Resposta bem sucedida
```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"
}
}
```
Salve o portador do token `txt_...` e os códigos de backup imediatamente. O e-mail
sintético interno, o hash do token, a senha e o hash de IP de limitação nunca são retornados.
### Erros
- `422` com `{"error":"validation_failed","details":...}` para nomes de usuário inválidos ou duplicados
ou senhas inválidas
- `429` com `{"error":"account_creation_rate_limited","retry_after_seconds":...}` quando o
O IP do solicitante já criou uma conta nos últimos cinco minutos
## Saúde
`GET /api/v1/health`
Esta rota é pública e útil para verificações de implantação e testes rápidos locais.
## Enfileirar uma mensagem enviada
`POST /api/v1/messages`
### Corpo da solicitação
```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 telefone do destinatário no formato E.164, obrigatório
- `body`: string obrigatória, de 1 a 1600 caracteres
- `estimated_cost_cents`: número inteiro positivo opcional, padrão para o custo de SMS configurado
- `idempotency_key`: string opcional, de 8 a 128 caracteres, com escopo definido por usuário
- `metadata`: objeto JSON opcional
`phone_number` é o campo destinatário de V1. Não envie `to`, a menos que uma versão futura da API o documente explicitamente.
As remessas API usam seleção automática de remetente. Os envios do aplicativo do navegador podem
escolha um número de marca conectado; Esse remetente selecionado passa a fazer parte do
solicitação de mensagem 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"
}'
```
### Respostas bem sucedidas
Mensagens recém-enfileiradas retornam `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
}
```
Se o mesmo usuário reproduzir o mesmo `idempotency_key` com a mesma carga de mensagem
e a mesma seleção de remetente, TextTree retorna `200 OK` com a mensagem existente
e `"replayed": true`.
### Respostas de erro- `422` com `{"error":"validation_failed","details":...}` quando o corpo está mal formado
- `403` com `{"error":"workspace_suppressed"}` quando o destinatário é bloqueado por uma exclusão do espaço de trabalho
- `402` com `{"error":"spend_limit_exceeded"}` quando o limite de gastos atual for excedido
- `409` com `{"error":"idempotency_conflict"}` quando uma chave idempotente é reutilizada com um
destinatário, corpo, custo ou remetente diferente
- `422` ou detalhes de falha vinculada ao provedor quando um remetente de aplicativo selecionado não é mais
está disponível para o espaço de trabalho
## Verifique o status de uma mensagem
`GET /api/v1/messages/:id`
Isso retorna o mesmo wrapper `message` usado nas respostas de construção.
O ciclo de vida atual de um estado de mensagem é:
-`queued`
-`dispatching`
-`sent`
-`delivered`
-`failed`
-`blocked`
`external_id` é concluído quando a execução orientada ao fornecedor tiver um identificador de fornecedor estável.
### Exemplo de status
```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
A criação da conta é iniciada automaticamente usando `POST /api/v1/accounts` e
`POST /mcp/accounts`, mas o envio de saída ainda requer a configuração do espaço de trabalho.
Antes que `POST /api/v1/messages` possa ter sucesso em um novo espaço de trabalho, o chamador ou
o operador deve:
- autenticar via TextTree e incluir um token com `messages:write`
- confirme se o destinatário não está sob exclusão ativa do espaço de trabalho
- definir um limite de gastos ativo em `/app`
- definir um remetente de teste, número de remetente ativo ou modo de envio automático
## API de números
`GET /api/v1/numbers` requer `numbers:read`.
`POST /api/v1/numbers` requer `numbers:write` e compra um número através do
Limite do provedor de mensagens TextTree. Inclui um `area_code` quando o
operadora deseja um número local. As compras ao vivo permanecem bloqueadas, a menos que a implantação
Ative explicitamente a barreira de proteção de compra de número ativo.
```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"
}'
```
Compras bem-sucedidas retornam `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"
}
```
## Limites atuais da fase alfa
A API do desenvolvedor **não** expõe atualmente:
- Endpoints CRUD herdados de metadados de consentimento/contato
- Endpoints CRUD de exclusões de espaço de trabalho
- limites de gastos nos endpoints CRUD
- criação direta de sessões de financiamento; use faturas de financiamento de integração para recargas de lançamento