Type de page: docs
API pour les développeurs
Contrats d'envoi de messages et de statuts pour l'alpha API actuel de TextTree.
Réponse directe
Contrats d'envoi de messages et de statuts pour l'alpha API actuel de TextTree.
Contenu source
# API pour les développeurs
Le API JSON actuel est intentionnellement rétréci. Il se concentre sur un chemin de production critique :
collez les SMS sortants et vérifiez leur statut.
## URL de base
Le développement local avec Phoenix s'exécute sur `http://localhost:4001`.
Tous les points de terminaison de développeur documentés se trouvent sous `/api/v1`.
## Authentification
Les appels authentifiés vers API nécessitent un jeton d'accès au porteur `txt_...` émis par TextTree.
Le même modèle d'identité locale est utilisé pour l'application de navigateur, le API pour les développeurs et
les itinéraires MCP. Les clés API `txk_...` héritées sont conservées en tant qu'enregistrements internes et ne sont pas
sont acceptés par `/api/v1/messages`.
```http
Autorisation : Porteur <textree_access_token>
Accepter : application/json
```
`POST /api/v1/messages` nécessite `messages:write`. Nombre de points de terminaison d'inventaire
nécessitent `numbers:read` ou `numbers:write`. Identités de messagerie, Google,
le portefeuille et l'agent sont normalisés avec la même identité locale de TextTree avant
autorisation.
## Démarrage du compte sans tête
Les clients AI et API peuvent créer un compte sans e-mail, Google OAuth ou
authentification du portefeuille à l'aide du nom d'utilisateur et du mot de passe de démarrage.
`POST /api/v1/accounts`
Cet itinéraire est public, uniquement JSON, et est limité à une création de compte réussie.
par adresse IP toutes les cinq minutes. TextTree stocke un hachage de l'adresse IP dans
le registre des limitations ; l'adresse IP brute n'est pas stockée.
### Corps de la requête
```json
{
"username": "agent-demo",
"mot de passe": "agrafe de batterie de cheval correcte"
}
```
### Réponse réussie
```json
{
"compte": {
"identifiant": "9d7d9df7-58a0-4716-b82e-7ad5e73f7b36",
"nom d'utilisateur": "agent-démo"
},
"backup_codes": ["AAAA-BBBB-CCCC-DDDD"],
"jeton": {
"type": "Porteur",
"access_token": "txt_...",
"scopes": ["mcp:read", "mcp:execute", "messages:write"],
"expires_at": "2026-06-03T15:30:00Z"
}
}
```
Enregistrez immédiatement le porteur du jeton `txt_...` et les codes de sauvegarde. L'e-mail
synthétique interne, le hachage du jeton, le mot de passe et le hachage IP de limitation ne sont jamais renvoyés.
### Erreurs
- `422` avec `{"error":"validation_failed","details":...}` pour les noms d'utilisateur invalides ou en double
ou mots de passe invalides
- `429` avec `{"error":"account_creation_rate_limited","retry_after_seconds":...}` lorsque le
L'adresse IP du demandeur a déjà créé un compte au cours des cinq dernières minutes
## Santé
`GET /api/v1/health`
Cette route est publique et est utile pour les vérifications de déploiement et les tests rapides locaux.
## Mettre en file d'attente un message sortant
`POST /api/v1/messages`
### Corps de la requête
```json
{
"numéro_téléphone": "+15551234567",
"body": "Votre code de vérification est 482019",
"estimated_cost_cents": 2,
"idempotency_key": "msg_2026_04_26_0001",
"métadonnées": {
"campaign": "invitation alpha",
"source": "API"
}
}
```
### Champs
- `phone_number` : numéro de téléphone du destinataire au format E.164, obligatoire
- `body` : chaîne obligatoire, 1 à 1600 caractères
- `estimated_cost_cents` : entier positif facultatif, par défaut le coût SMS configuré
- `idempotency_key` : chaîne facultative, de 8 à 128 caractères, limitée par utilisateur
- `metadata` : objet JSON optionnel
`phone_number` est le champ destinataire de la V1. N'envoyez pas `to` à moins qu'une future version de API ne le documente explicitement.
Les envois via API utilisent la sélection automatique de l'expéditeur. Les soumissions depuis l'application du navigateur peuvent
choisissez un numéro de marque connecté ; Cet expéditeur sélectionné fait partie du
demande de message idempotent.
### boucle
```bash
boucle https://api.texttree.ai/api/v1/messages \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{
"numéro_téléphone": "+15551234567",
"body": "Votre code de vérification est 482019",
"idempotency_key": "msg_2026_04_26_0001"
}'
```
### Réponses réussies
Les messages nouvellement mis en file d'attente renvoient `202 Accepted` :
```json
{
"message": {
"identifiant": "8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb",
"statut": "en file d'attente",
"numéro_téléphone": "+15551234567",
"body": "Votre code de vérification est 482019",
"provider": "messaging_provider",
"consent_status": "manquant",
"id_externe": nul,
"estimated_cost_cents": 2,
"idempotency_key": "msg_2026_04_26_0001",
"métadonnées": {
"campaign": "invitation alpha",
"source": "API"
},
"insert_at": "2026-04-26T20:44:12Z",
"updated_at": "2026-04-26T20:44:12Z",
"liens": {
"self": "/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb"
}
},
"rejoué": faux
}
```
Si le même utilisateur lit le même `idempotency_key` avec la même charge utile de message
et la même sélection d'expéditeur, TextTree renvoie `200 OK` avec le message existant
et `"replayed": true`.
### Réponses aux erreurs
- `422` avec `{"error":"validation_failed","details":...}` lorsque le corps est mal formé
- `403` avec `{"error":"workspace_suppressed"}` lorsque le destinataire est bloqué par une suppression d'espace de travail
- `402` avec `{"error":"spend_limit_exceeded"}` lorsque la limite de dépenses actuelle serait dépassée
- `409` avec `{"error":"idempotency_conflict"}` lorsqu'une clé idempotente est réutilisée avec un
destinataire, organisme, coût ou expéditeur différent
- `422` ou détails d'échec liés au fournisseur lorsqu'un expéditeur d'application sélectionné n'est plus
est disponible pour l'espace de travail
## Vérifier l'état d'un message
`GET /api/v1/messages/:id`
Cela renvoie le même wrapper `message` utilisé dans les réponses de build.
Le cycle de vie actuel d'un état de message est :
-`queued`
-`dispatching`
-`sent`
-`delivered`
-`failed`
-`blocked`
`external_id` se termine une fois que l'exécution orientée fournisseur a un identifiant de fournisseur stable.
### Exemple de statut
```bash
boucle https://api.texttree.ai/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```
```json
{
"message": {
"identifiant": "8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb",
"status": "livré",
"numéro_téléphone": "+15551234567",
"estimated_cost_cents": 2,
"liens": {
"self": "/api/v1/messages/8f3d0f4f-5ab3-4db9-bf6a-92c72bc1f2bb"
}
}
}
```
## Avant d'envoyer
La création de compte démarre automatiquement à l'aide de `POST /api/v1/accounts` et
`POST /mcp/accounts`, mais l'envoi sortant nécessite toujours la configuration de l'espace de travail.
Avant que `POST /api/v1/messages` puisse réussir dans un nouvel espace de travail, l'appelant ou
l'opérateur doit :
- s'authentifier via TextTree et inclure un token avec `messages:write`
- confirmer que le destinataire n'est pas en cours de suppression active de l'espace de travail
- définir une limite de dépenses actives sur `/app`
- définir un expéditeur de test, un numéro d'expéditeur en direct ou un mode d'expéditeur automatique
## API de nombres
`GET /api/v1/numbers` nécessite `numbers:read`.
`POST /api/v1/numbers` nécessite `numbers:write` et achète un numéro via le
Limite du fournisseur de messagerie TextTree. Inclut un `area_code` lorsque le
l'opérateur veut un numéro local. Les achats en direct restent bloqués sauf déploiement
Activez explicitement la barrière de protection contre les achats de numéros en direct.
```bash
boucle https://api.texttree.ai/api/v1/numbers \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN" \
-H "Type de contenu : application/json" \
-d '{
"code_zone": "415",
"friendly_name": "Ligne d'assistance"
}'
```
Les achats réussis renvoient `201 Created` :
```json
{
"numéro": {
"identifiant": "b86fbe4d-2b92-4664-8e91-d2ed1d37f827",
"numéro": "+14155550123",
"friendly_name": "Ligne d'assistance",
"capacités": ["sms"],
"statut": "connecté",
"inbound_webhook_url": "https://app.texttree.ai/webhooks/provider/incoming",
"compliance_status": "en attente"
},
"webhook_configuré" : faux,
"avertissement": "provider_inbound_webhook_configuration_api_not_documented"
}
```
## Limites actuelles de la phase alpha
Le API pour les développeurs n'indique **pas** actuellement :
- Points de terminaison CRUD hérités des métadonnées de consentement/contact
- Points de terminaison CRUD issus des suppressions d'espace de travail
- les dépenses limitent les points finaux CRUD
- création directe de séances de financement ; utiliser les factures de financement d'intégration pour les recharges de lancement