# Referência de API

URL canônica: https://texttree.ai/pt-br/docs/api-reference/
URL em Markdown: https://texttree.ai/pt-br/docs/api-reference.md
Tipo de página: docs
Translation status: draft
Legal status: english_controls

## Resumo

Referência SEO indexável para mensagens, números, webhooks, contatos e APIs de cobrança do TextTree.

## Conteúdo fonte

## Autenticação

Usa um token de acesso ao portador `txt_...` emitido por TextTree. Os tokens devem incluir o
escopo exigido pelo caminho, como `messages:write`, `numbers:read`,
`numbers:write`, `mcp:read` ou `mcp:execute`. As chaves de API herdadas `txk_...` não são
Eles não são aceitos pelas rotas API do desenvolvedor ou rotas MCP.

```http
Authorization: Bearer $TEXTREE_ACCESS_TOKEN
```

## Crie uma conta sem cabeça

```http
POST /api/v1/accounts
POST /mcp/accounts
```

Esses endpoints JSON públicos criam uma conta de agente com nome de usuário e senha sem
e-mail, Google OAuth ou autenticação de carteira. Ambas as rotas invocam o mesmo fluxo
e retornar códigos de backup únicos mais um token de portador `txt_...` de
TextTree.

Campos obrigatórios:

-`username`
-`password`

`/api/v1/accounts` aceita os campos de nível superior. `/mcp/accounts` aceita o
mesmos campos no nível superior ou aninhados em `account`.

### curl

```bash
curl https://api.texttree.ai/api/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "username": "agent-demo",
    "password": "correct horse battery staple"
  }'
```

Resposta:

```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"
  }
}
```

A inicialização da conta está limitada a uma criação de conta bem-sucedida por endereço IP
a cada cinco minutos. Tentativas repetidas de criação bem-sucedidas retornam
`429 account_creation_rate_limited` com `retry_after_seconds`.

## Enviar SMS

```http
POST /api/v1/messages
```

Campos obrigatórios:

-`phone_number`
-`body`

Campos opcionais:

-`idempotency_key`
-`metadata`

As remessas API usam seleção automática de remetente. As remessas originadas no aplicativo podem
selecione um número de marca conectado; TextTree trata o remetente selecionado como 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 appointment is tomorrow at 9 AM.",
    "idempotency_key": "appointment-123-reminder"
  }'
```

### JavaScript

```js
const response = await fetch("https://api.texttree.ai/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer undefined`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+15551234567",
    body: "Your appointment is tomorrow at 9 AM.",
    idempotency_key: "appointment-123-reminder",
  }),
});

const { message } = await response.json();
```

### Python

```py
import os
import requests

response = requests.post(
    "https://api.texttree.ai/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['TEXTREE_ACCESS_TOKEN']}"},
    json={
        "phone_number": "+15551234567",
        "body": "Your appointment is tomorrow at 9 AM.",
        "idempotency_key": "appointment-123-reminder",
    },
    timeout=10,
)

message = response.json()["message"]
```

### Elixir

```elixir
Mix.install([:req])

%{body: %{"message" => message}} =
  Req.post!(
    "https://api.texttree.ai/api/v1/messages",
    auth: {:bearer, System.fetch_env!("TEXTREE_ACCESS_TOKEN")},
    json: %{
      phone_number: "+15551234567",
      body: "Your appointment is tomorrow at 9 AM.",
      idempotency_key: "appointment-123-reminder"
    }
  )
```

Resposta:

```json
{
  "message": {
    "id": "msg_123",
    "status": "queued"
  }
}
```

## Status da mensagem

```http
GET /api/v1/messages/{id}
```

### curl

```bash
curl https://api.texttree.ai/api/v1/messages/msg_123 \
  -H "Authorization: Bearer $TEXTREE_ACCESS_TOKEN"
```

Resposta:

```json
{
  "message": {
    "id": "msg_123",
    "status": "delivered",
    "phone_number": "+15551234567",
    "segments": 1,
    "cost_cents": 1,
    "created_at": "2026-04-28T14:00:00Z"
  }
}
```

Use a página Mensagens para depurar a linha do tempo, webhooks e falhas.

Reutilize um `idempotency_key` com um destinatário, corpo, custo ou remetente selecionado
retornos diferentes um conflito de idempotência.

## Números de telefone

```http
GET /api/v1/numbers
POST /api/v1/numbers
```

`GET` requer `numbers:read`. `POST` requer `numbers:write` e compra um
número através do limite do provedor de mensagens TextTree. `area_code` é compatível
pela intenção de adquirir números locais. Compras ao vivo exigem barreira de proteção
compra explícita de números ativos da implantação.

```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"
  }'
```

Resposta:

```json
{
  "number": {
    "id": "num_123",
    "number": "+14155550123",
    "friendly_name": "Support line",
    "status": "connected",
    "compliance_status": "pending"
  },
  "webhook_configured": false,
  "warning": "provider_inbound_webhook_configuration_api_not_documented"
}
```