Seitentyp: docs
Entwickler-API
Nachrichtenversand und Statusverträge für die aktuelle TextTree-Alpha-API.
Direkte Antwort
Nachrichtenversand und Statusverträge für die aktuelle TextTree-Alpha-API.
Seiteninhalt
# API für Entwickler
Die aktuelle JSON-API ist absichtlich eng. Es konzentriert sich auf einen kritischen Produktionspfad:
Stellen Sie ausgehende SMS in die Warteschlange und überprüfen Sie deren Status.
## Basis-URL
Die lokale Entwicklung mit Phoenix läuft unter `http://localhost:4001`.
Alle dokumentierten Entwicklerendpunkte leben unter `/api/v1`.
## Authentifizierung
Für authentifizierte Aufrufe der API ist ein von TextTree ausgestelltes Bearer-Zugriffstoken `txt_...` erforderlich.
Für die Browser-App, die Entwickler-API und wird dasselbe lokale Identitätsmodell verwendet
MCP-Routen. Legacy-API-Schlüssel `txk_...` werden als interne Datensätze aufbewahrt und sind es nicht
werden von `/api/v1/messages` akzeptiert.
```http
Autorisierung: Inhaber <textree_access_token>
Akzeptieren: application/json
```
`POST /api/v1/messages` erfordert `messages:write`. Anzahl der Inventarendpunkte
erfordern `numbers:read` oder `numbers:write`. E-Mail-Identitäten, Google,
Wallet und Agent werden zuvor auf dieselbe lokale TextTree-Identität normalisiert
Autorisierung.
## Headless-Kontostart
AI- und API-Kunden können ein Konto ohne E-Mail, Google OAuth oder erstellen
Wallet-Authentifizierung mit Benutzername und Passwort beim Booten.
`POST /api/v1/accounts`
Diese Route ist öffentlich, nur JSON und auf die erfolgreiche Kontoerstellung beschränkt
pro IP-Adresse alle fünf Minuten. TextTree speichert einen Hash der IP-Adresse
das Beschränkungsregister; Die Roh-IP wird nicht gespeichert.
### Anforderungstext
```json
{
„Benutzername“: „Agent-Demo“,
„Passwort“: „Korrekte Pferdebatterieklammer“
}
```
### Erfolgreiche Antwort
```json
{
"Konto": {
„id“: „9d7d9df7-58a0-4716-b82e-7ad5e73f7b36“,
„Benutzername“: „agent-demo“
},
„backup_codes“: [„YYYY-BBBB-CCCC-DDDD“],
„Token“: {
„Typ“: „Träger“,
„access_token“: „txt_…“,
„scopes“: [„mcp:read“, „mcp:execute“, „messages:write“],
„expires_at“: „2026-06-03T15:30:00Z“
}
}
```
Speichern Sie den Token-Inhaber `txt_...` und die Sicherungscodes sofort. Die E-Mail
Interne Synthese, der Token-Hash, das Passwort und der drosselnde IP-Hash werden nie zurückgegeben.
### Fehler
- `422` mit `{"error":"validation_failed","details":...}` für ungültige oder doppelte Benutzernamen
oder ungültige Passwörter
- `429` mit `{"error":"account_creation_rate_limited","retry_after_seconds":...}` wenn die
Die IP des Antragstellers hat in den letzten fünf Minuten bereits ein Konto erstellt
## Gesundheit
`GET /api/v1/health`
Diese Route ist öffentlich und eignet sich für Bereitstellungsüberprüfungen und lokale Schnelltests.
## Eine ausgehende Nachricht in die Warteschlange stellen
`POST /api/v1/messages`
### Anforderungstext
```json
{
„phone_number“: „+15551234567“,
„body“: „Ihr Bestätigungscode ist 482019“,
„estimated_cost_cents“: 2,
„idempotency_key“: „msg_2026_04_26_0001“,
„Metadaten“: {
„Kampagne“: „Alpha-Einladung“,
„Quelle“: „API“
}
}
```
### Felder
- `phone_number`: Telefonnummer des Empfängers im E.164-Format, erforderlich
- `body`: erforderliche Zeichenfolge, 1 bis 1600 Zeichen
- `estimated_cost_cents`: optionale positive Ganzzahl, standardmäßig die konfigurierten SMS-Kosten
- `idempotency_key`: optionale Zeichenfolge, 8 bis 128 Zeichen, pro Benutzer gültig
- `metadata`: optionales JSON-Objekt
`phone_number` ist das Empfängerfeld von V1. Senden Sie `to` nicht, es sei denn, eine zukünftige Version der API dokumentiert dies ausdrücklich.
API-Sendungen nutzen die automatische Absenderauswahl. Übermittlungen aus der Browser-App können
Wählen Sie eine verbundene Markennummer; Der ausgewählte Absender wird Teil des
idempotente Nachrichtenanforderung.
### locken
```bash
Curl https://api.texttree.ai/api/v1/messages \
-H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
-H „Inhaltstyp: application/json“ \
-d '{
„phone_number“: „+15551234567“,
„body“: „Ihr Bestätigungscode ist 482019“,
„idempotency_key“: „msg_2026_04_26_0001“
}'
```
### Erfolgreiche Antworten
Neu in die Warteschlange gestellte Nachrichten geben `202 Accepted` zurück:
```json
{
„Nachricht“: {
„id“: „8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“,
„status“: „in der Warteschlange“,
„phone_number“: „+15551234567“,
„body“: „Ihr Bestätigungscode ist 482019“,
„provider“: „messaging_provider“,
„consent_status“: „fehlt“,
„external_id“: null,
„estimated_cost_cents“: 2,
„idempotency_key“: „msg_2026_04_26_0001“,
„Metadaten“: {
„Kampagne“: „Alpha-Einladung“,
„Quelle“: „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“
}
},
„wiedergegeben“: falsch
}
```
Wenn derselbe Benutzer dasselbe `idempotency_key` mit derselben Nachrichtennutzlast abspielt
und der gleichen Absenderauswahl gibt TextTree `200 OK` mit der vorhandenen Nachricht zurück
und `"replayed": true`.
### Fehlerantworten
- `422` mit `{"error":"validation_failed","details":...}`, wenn der Körper schlecht geformt ist
- `403` mit `{"error":"workspace_suppressed"}`, wenn der Empfänger durch eine Arbeitsbereichslöschung blockiert wird
- `402` mit `{"error":"spend_limit_exceeded"}`, wenn das aktuelle Ausgabenlimit überschritten würde
- `409` mit `{"error":"idempotency_conflict"}`, wenn ein Idempotenzschlüssel mit a wiederverwendet wird
unterschiedlicher Empfänger, Körper, Kosten oder Absender
- `422` oder anbieterbezogene Fehlerdetails, wenn ein ausgewählter App-Absender nicht mehr verfügbar ist
steht für den Arbeitsbereich zur Verfügung
## Überprüfen Sie den Status einer Nachricht
`GET /api/v1/messages/:id`
Dadurch wird derselbe `message`-Wrapper zurückgegeben, der in den Build-Antworten verwendet wird.
Der aktuelle Lebenszyklus eines Nachrichtenstatus ist:
- `queued`
- `dispatching`
- `sent`
- `delivered`
- `failed`
- `blocked`
`external_id` wird abgeschlossen, sobald die lieferantenorientierte Ausführung über eine stabile Lieferantenkennung verfügt.
### Statusbeispiel
```bash
Curl https://api.texttree.ai/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb \
-H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“
```
```json
{
„Nachricht“: {
„id“: „8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“,
„status“: „geliefert“,
„phone_number“: „+15551234567“,
„estimated_cost_cents“: 2,
"Links": {
„self“: „/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb“
}
}
}
```
## Vor dem Senden
Die Kontoerstellung wird mit `POST /api/v1/accounts` und gebootet
`POST /mcp/accounts`, für ausgehendes Senden muss jedoch weiterhin der Arbeitsbereich konfiguriert werden.
Bevor `POST /api/v1/messages` in einem neuen Arbeitsbereich erfolgreich sein kann, muss der Aufrufer bzw
Der Betreiber muss:
- Authentifizieren Sie sich über TextTree und fügen Sie ein Token mit `messages:write` hinzu
- Bestätigen Sie, dass für den Empfänger kein aktiver Arbeitsbereich gelöscht wird
- Legen Sie ein aktives Ausgabenlimit für `/app` fest
- Legen Sie einen Testabsender, eine Live-Absendernummer oder einen automatischen Absendermodus fest
## Numbers-API
`GET /api/v1/numbers` erfordert `numbers:read`.
`POST /api/v1/numbers` erfordert `numbers:write` und kauft eine Nummer über das
Limit des TextTree-Messaging-Anbieters. Enthält ein `area_code`, wenn das
Betreiber möchte eine lokale Nummer. Live-Käufe bleiben bis zur Bereitstellung blockiert
Aktivieren Sie explizit die Schutzbarriere für den Kauf von Live-Nummern.
```bash
Curl https://api.texttree.ai/api/v1/numbers \
-H „Autorisierung: Inhaber $TEXTREE_ACCESS_TOKEN“ \
-H „Inhaltstyp: application/json“ \
-d '{
"area_code": "415",
„Friendly_name“: „Support-Hotline“
}'
```
Erfolgreiche Käufe geben `201 Created` zurück:
```json
{
"Nummer": {
„id“: „b86fbe4d-2b92-4664-8e91-d2ed1d37f827“,
„Nummer“: „+14155550123“,
"Friendly_name": "Support-Hotline",
„capabilities“: [„sms“],
„status“: „verbunden“,
„inbound_webhook_url“: „https://app.texttree.ai/webhooks/provider/incoming",
„compliance_status“: „ausstehend“
},
„webhook_configured“: false,
„warning“: „provider_inbound_webhook_configuration_api_not_documented“
}
```
## Aktuelle Alpha-Phasen-Grenzwerte
Die Entwickler-API stellt derzeit Folgendes **nicht** zur Verfügung:
- Aus Einwilligungs-/Kontaktmetadaten geerbte CRUD-Endpunkte
– CRUD-Endpunkte aus Arbeitsbereichslöschungen
- Ausgabenlimits für CRUD-Endpunkte
- direkte Erstellung von Finanzierungssitzungen; Verwenden Sie Onboarding-Finanzierungsrechnungen für Startaufladungen