# Référence API

URL canonique: https://texttree.ai/fr/docs/api-reference/
URL Markdown: https://texttree.ai/fr/docs/api-reference.md
Type de page: docs
Translation status: draft
Legal status: english_controls

## Résumé

Référence indexable pour le référencement des messages, numéros, webhooks, contacts et API de facturation TextTree.

## Contenu source

## Authentification

Utilise un jeton d'accès au porteur `txt_...` émis par TextTree. Les jetons doivent inclure le
portée requise par le chemin, telle que `messages:write`, `numbers:read`,
`numbers:write`, `mcp:read` ou `mcp:execute`. Les clés de API héritées de `txk_...` ne le sont pas.
ne sont pas acceptés par les chemins de développement API ou les chemins MCP.

```http
Autorisation : Porteur $TEXTREE_ACCESS_TOKEN
```

## Créer un compte sans tête

```http
POST /api/v1/comptes
POST /mcp/comptes
```

Ces points de terminaison publics JSON créent un compte d'agent avec un nom d'utilisateur et un mot de passe sans
e-mail, Google OAuth ou authentification par portefeuille. Les deux routes invoquent le même flux
et renvoie les codes de sauvegarde uniques plus un jeton de porteur `txt_...` de
TextTree.

Champs obligatoires :

-`username`
-`password`

`/api/v1/accounts` accepte les champs de niveau supérieur. `/mcp/accounts` accepte le
mêmes champs au niveau supérieur ou imbriqués dans `account`.

### boucle

```bash
boucle https://api.texttree.ai/api/v1/accounts \
-H "Type de contenu : application/json" \
-d '{
"username": "agent-demo",
"mot de passe": "agrafe de batterie de cheval correcte"
  }'
```

Réponse :

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

Le démarrage du compte est limité à une création de compte réussie par adresse IP
toutes les cinq minutes. Les tentatives de création répétées et réussies reviennent
`429 account_creation_rate_limited` avec `retry_after_seconds`.

## Envoyer SMS

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

Champs obligatoires :

-`phone_number`
-`body`

Champs facultatifs :

-`idempotency_key`
-`metadata`

Les envois via API utilisent la sélection automatique de l'expéditeur. Les envois provenant de l'application peuvent
sélectionner un numéro de marque connectée ; TextTree traite l'expéditeur sélectionné comme faisant 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 rendez-vous est demain à 9h.",
"idempotency_key": "rendez-vous-123-rappel"
  }'
```

### JavaScript

```js
réponse const = wait fetch("https://api.texttree.ai/api/v1/messages", {
méthode : "POST",
en-têtes : {
Autorisation : `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
"Content-Type": "application/json",
  },
corps : JSON.stringify({
numéro de téléphone : "+15551234567",
body: "Votre rendez-vous est demain à 9h.",
idempotency_key : "rendez-vous-123-rappel",
  }),
});

const { message } = wait réponse.json();
```

### Python

```py
t'importer
demandes d'importation

réponse = requêtes.post(
"https://api.texttree.ai/api/v1/messages",
headers={"Autorisation": f"Bearer {os.environ['TEXTREE_ACCESS_TOKEN']}"},
json={
"numéro_téléphone": "+15551234567",
"body": "Votre rendez-vous est demain à 9h.",
"idempotency_key": "rendez-vous-123-rappel",
    },
délai d'attente = 10,
)

message = réponse.json()["message"]
```

### Elixir

```élixir
Mix.install([:req])

%{body: %{"message" => message}} =
Post demandé !(
"https://api.texttree.ai/api/v1/messages",
auth : {:bearer, System.fetch_env!("TEXTREE_ACCESS_TOKEN")},
json : %{
numéro de téléphone : "+15551234567",
body: "Votre rendez-vous est demain à 9h.",
idempotency_key : "rendez-vous-123-rappel"
    }
  )
```

Réponse :

```json
{
"message": {
"identifiant": "msg_123",
"status": "en file d'attente"
  }
}
```

## État du message

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

### boucle

```bash
boucle https://api.texttree.ai/api/v1/messages/msg_123 \
-H "Autorisation : Porteur $TEXTREE_ACCESS_TOKEN"
```

Réponse :

```json
{
"message": {
"identifiant": "msg_123",
"status": "livré",
"numéro_téléphone": "+15551234567",
"segments": 1,
"cost_cents": 1,
"created_at": "2026-04-28T14:00:00Z"
  }
}
```

Utilisez la page Messages pour déboguer la chronologie, les webhooks et les plantages.

Réutiliser un `idempotency_key` avec un destinataire, un corps, un coût ou un expéditeur sélectionné
différents renvoie un conflit d'idempotence.

## Numéros de téléphone

```http
OBTENIR /api/v1/numéros
POST /api/v1/numéros
```

`GET` nécessite `numbers:read`. `POST` nécessite `numbers:write` et achète un
numéro via la limite du fournisseur de messagerie TextTree. `area_code` est pris en charge
pour l'intention d'acheter des numéros locaux. Les achats en direct nécessitent la barrière de protection
achat explicite de numéros en direct du déploiement.

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

Réponse :

```json
{
"numéro": {
"id": "num_123",
"numéro": "+14155550123",
"friendly_name": "Ligne d'assistance",
"statut": "connecté",
"compliance_status": "en attente"
  },
"webhook_configuré" : faux,
"avertissement": "provider_inbound_webhook_configuration_api_not_documented"
}
```