Référence API

API Comptes Twilio

Enregistrez et gérez les comptes Twilio qu'Aethex utilise pour piloter vos numéros de téléphone Twilio. Chaque compte peut contenir jusqu'à 32 comptes Twilio actifs simultanément. Nécessite la portée twilio_accounts:read ou twilio_accounts:write. Le même compte envoie vos messages texte. Il n'y a rien à relier une seconde fois et aucun fournisseur de messagerie à choisir : vous désignez lequel de vos numéros envoie les textos, et s'il les reçoit, sur le numéro lui-même avec PATCH /phone-numbers/{id} et sms_sender / sms_inbound. Twilio est interrogé sur la capacité du numéro à porter des SMS, et une ligne réservée à la voix est refusée. Ce qu'un agent peut dire s'écrit à part, dans Messages texte.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 4
Portées: twilio_accounts:readtwilio_accounts:write

POST/twilio-accounts

Valider une paire Account SID/Auth Token Twilio, puis la stocker chiffrée pour la numérotation sortante et la vérification des webhooks entrants.

Enregistrer un compte Twilio

Valide les identifiants fournis auprès de Twilio, puis persiste les données et retourne le nouvel enregistrement. L'auth_token est en écriture seule et n'apparaît jamais dans aucune réponse ou journal. Limite : 5 enregistrements par 60 secondes ; plafond de 32 comptes actifs par compte.

Corps de la requête

account_sidstringrequis
Account SID Twilio ; littéralement AC suivi d'exactement 32 caractères hexadécimaux. Insensible à la casse en entrée ; longueur totale : 34 caractères.
auth_tokenstringrequis
Auth Token Twilio (1–128 caractères). En écriture seule : validé à l'enregistrement, stocké chiffré au repos, jamais retourné.
friendly_namestringoptionnel
Libellé lisible affiché dans le portail développeur (max 255 caractères, texte brut).

Erreurs

422Format de SID invalide

account_sid n'est pas AC suivi de 32 caractères hex, ou auth_token/friendly_name violent leurs contraintes.

Copiez l'Account SID exactement depuis la console Twilio ; supprimez les espaces.

422Twilio a rejeté les identifiants

Twilio a répondu avec une erreur d'autorisation : mauvais Auth Token, token révoqué, ou token n'autorisant pas l'accès au SID fourni.

Recopiez l'Auth Token depuis la console Twilio et vérifiez que les deux valeurs proviennent du même compte.

422Account SID Twilio introuvable

L'account_sid fourni n'existe pas sur Twilio. Généralement une faute de frappe ou un compte supprimé.

Recollectez l'Account SID depuis la console Twilio.

409Account SID déjà enregistré pour ce compte

Ce compte possède déjà un enregistrement actif pour le même account_sid.

Continuez avec l'enregistrement existant, ou supprimez-le d'abord avec DELETE /twilio-accounts/{account_id}.

409Account SID réclamé par un autre compte

Un autre compte possède déjà un enregistrement actif pour cet account_sid.

Demandez au propriétaire précédent de libérer le SID, ou ouvrez un ticket de support.

409Plafond de comptes actifs atteint

Votre compte possède déjà 32 comptes Twilio actifs.

Libérez un compte inutilisé via DELETE /twilio-accounts/{account_id} avant d'en enregistrer un nouveau.

429Limite de débit d'enregistrement

Plus de 5 appels POST /twilio-accounts depuis ce compte dans les 60 dernières secondes.

Attendez le nombre de secondes indiqué dans Retry-After, puis réessayez.

503API Twilio inaccessible

Twilio n'a pas répondu dans le délai de validation, ou a retourné un 5xx.

Réessayez sous peu. Si Twilio signale un incident, attendez qu'il soit résolu.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/twilio-accounts \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_sid": "AC0123456789abcdef0123456789abcdef",
    "auth_token": "your_twilio_auth_token",
    "friendly_name": "Production Twilio account"
  }'

201 Réponse

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "account_sid": "AC0123456789abcdef0123456789abcdef",
  "friendly_name": "Production Twilio account",
  "status": "active",
  "created_at": "2025-01-16T12:00:00Z",
  "updated_at": "2025-01-16T12:00:00Z"
}

GET/twilio-accounts

Liste paginée de tous les comptes Twilio actifs sur votre compte.

Lister les comptes Twilio

Retourne tous les comptes Twilio actifs, ordonnés par created_at décroissant. Les comptes libérés sont filtrés. Nécessite la portée twilio_accounts:read.

Chemin & Requête

offsetintegeroptionnel
Nombre de résultats à ignorer (par défaut : 0 ; minimum : 0).
limitintegeroptionnel
Nombre maximum de résultats (par défaut : 50 ; minimum : 1 ; maximum : 200).

Erreurs

422Paramètre de pagination invalide

offset est négatif, ou limit est hors de [1, 200].

Envoyez offset >= 0 et 1 <= limit <= 200.

Réponse

json

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "account_sid": "AC0123456789abcdef0123456789abcdef",
      "friendly_name": "Production Twilio account",
      "status": "active",
      "created_at": "2025-01-16T12:00:00Z",
      "updated_at": "2025-01-16T12:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/twilio-accounts/:account_id

Récupérer un seul compte Twilio par UUID.

Obtenir un compte Twilio

Recherche par clé primaire, limitée au compte. Les comptes libérés sont signalés comme introuvables. Nécessite la portée twilio_accounts:read.

Chemin & Requête

account_idstringrequis
UUID du compte Twilio (le champ id de la réponse d'enregistrement).

Erreurs

404Compte Twilio introuvable

Aucun enregistrement actif avec l'UUID donné n'existe sur ce compte.

Confirmez que l'account_id provient de GET /twilio-accounts de ce compte.

422UUID invalide

Le paramètre de chemin account_id n'est pas un UUID valide.

Passez le champ id retourné par POST ou GET /twilio-accounts.

Réponse

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "account_sid": "AC0123456789abcdef0123456789abcdef",
  "friendly_name": "Production Twilio account",
  "status": "active",
  "created_at": "2025-01-16T12:00:00Z",
  "updated_at": "2025-01-16T12:00:00Z"
}

DELETE/twilio-accounts/:account_id

Libération idempotente qui passe l'enregistrement à `released` et supprime l'auth token stocké.

Libérer un compte Twilio

Passe le status de active à released, libérant l'Account SID pour réenregistrement ultérieur, et détruit l'auth token stocké. Idempotent : retourne 204 No Content dans tous les cas. Nécessite la portée twilio_accounts:write.

Chemin & Requête

account_idstringrequis
UUID du compte Twilio.

Erreurs

422UUID invalide

Le paramètre de chemin account_id n'est pas un UUID valide.

Passez le champ id retourné par POST ou GET /twilio-accounts.