Référence API

Connexion opérateur

Liez un compte Telnyx avec une clé API et provisionnez automatiquement un trunk SIP fonctionnel à partir d'un de vos numéros — sans passer par le portail de l'opérateur ni copier d'identifiants SIP.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 5
Portées: carrier_accounts:readcarrier_accounts:writesip_trunks:writephone_numbers:write

POST/integrations/telephony/carriers

Valider une clé API opérateur et la stocker (chiffrée).

Lier un compte opérateur

Valide la clé API auprès de l'opérateur, puis la stocke chiffrée au repos. La clé n'est jamais renvoyée dans une réponse. Utilise le scope self-serve carrier_accounts:write. Un compte actif par opérateur et par locataire — libérez l'existant avant d'en lier un autre.

Corps de la requête

providerstringrequis
Opérateur à lier : telnyx.
api_keystringrequis
La clé API REST de l'opérateur. Validée auprès de l'opérateur avant stockage ; jamais renvoyée.
labelstringoptionnel
Libellé lisible optionnel.

Erreurs

422Entité non traitable

L'opérateur a rejeté la clé API, ou le fournisseur est inconnu.

Vérifiez la clé API et que provider vaut telnyx.

409Conflit

Un compte opérateur pour ce fournisseur est déjà lié.

Libérez le compte existant avant d'en lier un autre.

429Trop de requêtes

Limite de liaison par locataire dépassée (5/min).

Réessayez après l'intervalle Retry-After.

502Bad Gateway

L'API de l'opérateur a rejeté la validation de la clé avec une erreur en amont (par ex. une limite de débit côté opérateur sur la lecture du solde/profil).

Réessayez sous peu ; si cela persiste, vérifiez l'état de l'API du compte opérateur.

503Service indisponible

L'API opérateur était injoignable, le limiteur de débit est hors ligne, ou la clé de chiffrement est absente.

Réessayez sous peu ; si cela persiste, contactez le support.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/carriers \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "telnyx",
    "api_key": "KEY0123...your-telnyx-api-key",
    "label": "Production Telnyx"
  }'

201 Réponse

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "telnyx",
  "label": "Production Telnyx",
  "status": "active",
  "created_at": "2026-07-24T12:00:00Z",
  "updated_at": "2026-07-24T12:00:00Z"
}

POST/integrations/telephony/carriers/:id/connect

Auto-provisionnement : connexion opérateur → edge Aethex → trunk SIP.

Connecter un numéro

Pilote l'API REST de l'opérateur pour créer une connexion SIP pointant vers l'edge Aethex et attribuer phone_number, puis crée le trunk SIP Aethex correspondant et — si agent_id est fourni — route les appels entrants du numéro vers cet agent. Telnyx est en mode register (Credential Connection Telnyx). Les objets côté opérateur sont annulés si la création du trunk échoue.

Chemin & Requête

idstringrequis
UUID du compte opérateur lié.

Corps de la requête

phone_numberstringrequis
Numéro E.164 du compte opérateur à connecter (ex. +14155550100).
agent_idstringoptionnel
Router les appels entrants de ce numéro vers cet agent.

Erreurs

404Introuvable

Compte lié inexistant, ou agent_id introuvable.

Liez d'abord le compte opérateur ; vérifiez l'id de l'agent.

422Entité non traitable

L'opérateur a rejeté la clé API stockée, ou le corps est mal formé.

Reliez le compte opérateur avec une clé valide ; vérifiez que phone_number est en E.164.

409Conflit

Le numéro est déjà rattaché à un trunk (sur ce locataire ou un autre).

Détachez d'abord l'enregistrement existant, ou utilisez un numéro non connecté.

429Trop de requêtes

Limite de débit de connexion par compte dépassée (3/min).

Réessayez après l'intervalle Retry-After.

502Passerelle incorrecte

Telnyx a refusé une étape de provisionnement (ex. le numéro n'est pas sur le compte).

Confirmez que le numéro est sur le compte Telnyx.

503Service indisponible

L'API opérateur était injoignable, ou la clé de chiffrement est absente.

Réessayez sous peu.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/carriers/a1b2c3d4-.../connect \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "agent_id": "9c2f1e6a-..."
  }'

201 Réponse

json

{
  "carrier_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "telnyx",
  "phone_number": "+14155550100",
  "sip_trunk_id": "7f3a2b10-...",
  "agent_id": "9c2f1e6a-...",
  "status": "connected"
}

GET/integrations/telephony/carriers

Lister les comptes opérateur liés de ce locataire.

Lister les comptes opérateur

Renvoie les comptes opérateur liés (métadonnées uniquement — la clé API n'est jamais renvoyée). Paginé.

Chemin & Requête

limitintegeroptionnel
Nombre de lignes à renvoyer. De 1 à 200, 50 par défaut.
offsetintegeroptionnel
Nombre de lignes à ignorer avant la première renvoyée. 0 par défaut.

Requête

json

curl https://api.aethexai.com/api/v1/integrations/telephony/carriers \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "data": [
    { "id": "a1b2c3d4-...", "provider": "telnyx", "label": "Production Telnyx", "status": "active" }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/integrations/telephony/carriers/:id

Récupérer un compte opérateur lié.

Obtenir un compte opérateur

Renvoie les métadonnées d'un compte opérateur (fournisseur, libellé, statut). La clé API n'est jamais renvoyée.

Chemin & Requête

idstringrequis
UUID du compte opérateur.

Erreurs

404Introuvable

Aucun compte opérateur avec cet id pour ce locataire.

Vérifiez l'id du compte.

Requête

json

curl https://api.aethexai.com/api/v1/integrations/telephony/carriers/a1b2c3d4-... \
  -H "X-API-Key: $AETHEX_API_KEY"

Réponse 200

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "telnyx",
  "label": "Production Telnyx",
  "status": "active"
}

DELETE/integrations/telephony/carriers/:id

Libérer un compte opérateur lié (idempotent).

Libérer un compte opérateur

Marque le compte opérateur comme libéré. Idempotent — renvoie 204 qu'il ait été actif, déjà libéré ou absent. Les trunks SIP déjà provisionnés à partir de lui restent intacts.

Chemin & Requête

idstringrequis
UUID du compte opérateur.