Référence API

Microsoft Teams Phone

Connectez un locataire Microsoft Teams, associez l'un de vos numéros Teams existants à un agent, et passez des appels sortants via Azure Communication Services. Tous les endpoints se trouvent sous /integrations/telephony/msteams et s'authentifient avec l'en-tête X-API-Key.

URL de base: https://api.aethexai.com/api/v1
Endpoints: 6
Portées: msteams:readmsteams:writecalls:writephone_numbers:write

POST/integrations/telephony/msteams/connect

Lancer le consentement administrateur Microsoft

Démarrer la connexion Teams

Lance le parcours de consentement administrateur Microsoft. Renvoie une consent_url vers laquelle envoyer votre administrateur Teams ou Général, et state_expires_in, le nombre de secondes pendant lesquelles le lien reste valide. Aucune connexion n'est enregistrée tant que l'administrateur n'a pas approuvé. Aethex ne stocke que l'identifiant de votre locataire Microsoft, jamais un secret. Nécessite la portée msteams:write.

Erreurs

503Non activé

La connexion Microsoft Teams Phone n'est pas activée ou pas configurée sur ce déploiement.

Contactez [email protected] pour activer Microsoft Teams sur votre compte.

Requête

json

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

Réponse 200

json

{
  "consent_url": "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?client_id=...&response_type=code&scope=openid%20https%3A%2F%2Fgraph.microsoft.com%2F.default&state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&redirect_uri=...",
  "state_expires_in": 600
}

GET/integrations/telephony/msteams

Lire la connexion Teams reliée

Obtenir la connexion

Renvoie la connexion Microsoft Teams active de votre locataire, y compris le locataire Microsoft relié (home_tenant_id) et son statut. Nécessite la portée msteams:read.

Erreurs

404Non connecté

Votre locataire n'a pas encore de connexion Microsoft Teams.

Exécutez POST /integrations/telephony/msteams/connect et terminez le consentement administrateur.

Requête

json

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

Réponse 200

json

{
  "id": "1f77c0de-4b3a-4d2e-9c11-2a6b8e0f1234",
  "provider": "msteams",
  "home_tenant_id": "8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d",
  "display_name": "",
  "status": "active",
  "created_at": "2026-07-31T12:00:00Z",
  "updated_at": "2026-07-31T12:05:00Z"
}

GET/integrations/telephony/msteams/resource-accounts

Numéros Teams reliés à Aethex, plus la commande de configuration

Lister les comptes de ressource

Liste les comptes de ressource Teams que vous avez reliés à Aethex et le numéro affecté à chacun. Renvoie aussi connect_command : la ligne Microsoft Teams PowerShell à usage unique que votre administrateur exécute pour créer un compte de ressource relié. Les valeurs ApplicationId et AcsResourceId sont pré-remplies dans la commande renvoyée, donc exécutez-la telle quelle, en remplaçant uniquement YOUR-TEAMS-DOMAIN. Nécessite la portée msteams:read.

Erreurs

404Non connecté

Votre locataire n'a pas encore de connexion Microsoft Teams.

Exécutez d'abord POST /integrations/telephony/msteams/connect et terminez le consentement administrateur.

409Reconnexion requise

La session Microsoft capturée à la connexion a expiré.

Appelez à nouveau POST /integrations/telephony/msteams/connect pour réapprouver.

502Erreur Microsoft Graph

Microsoft a renvoyé une erreur lors de la récupération de vos comptes de ressource.

Réessayez sous peu. Si le problème persiste, contactez le support.

Requête

json

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

Réponse 200

json

{
  "resource_accounts": [
    {
      "id": "6c7d8e9f-0a1b-2c3d-4e5f-60718293a4b5",
      "user_principal_name": "[email protected]",
      "display_name": "Aethex Voice",
      "phone_number": "+14155550100"
    }
  ],
  "connect_command": "Connect-MicrosoftTeams; $ra = New-CsOnlineApplicationInstance -UserPrincipalName '[email protected]' -ApplicationId '<application-id>' -DisplayName 'Aethex Voice'; Set-CsOnlineApplicationInstance -Identity '[email protected]' -ApplicationId '<application-id>' -AcsResourceId '<acs-resource-id>'; Sync-CsOnlineApplicationInstance -ObjectId $ra.ObjectId -ApplicationId '<application-id>'"
}

POST/integrations/telephony/msteams/attach

Acheminer un numéro Teams vers un agent

Associer un numéro

Lie le numéro de téléphone d'un compte de ressource relié à l'un de vos agents, afin que les appels entrants vers le numéro soient pris en charge par cet agent. Idempotent par numéro : réassocier repointe le numéro vers l'agent indiqué. Nécessite la portée msteams:write.

Corps de la requête

resource_account_idstringrequis
Un id renvoyé par GET /integrations/telephony/msteams/resource-accounts.
agent_idstring (uuid)requis
L'agent qui doit répondre aux appels vers ce numéro. Doit appartenir à votre compte.
friendly_namestringoptionnel
Libellé facultatif pour le numéro. Par défaut, le nom d'affichage du compte de ressource.

Erreurs

404Introuvable

L'agent n'existe pas sur votre compte, le compte de ressource n'est pas relié à Aethex pour votre locataire, ou vous n'avez aucune connexion Teams.

Vérifiez l'agent_id et le resource_account_id, et confirmez la connexion avec GET /integrations/telephony/msteams.

409Reconnexion requise

La session Microsoft capturée à la connexion a expiré.

Appelez à nouveau POST /integrations/telephony/msteams/connect pour réapprouver, puis réessayez.

409Numéro indisponible

Aucun numéro n'est encore affecté au compte de ressource, ou le numéro est déjà connecté à un autre compte Aethex.

Affectez un numéro au compte de ressource dans le Centre d'administration Teams, ou libérez-le d'abord de l'autre compte.

502Erreur Microsoft Graph

Microsoft a renvoyé une erreur lors de l'autorisation du numéro.

Réessayez sous peu. Si le problème persiste, contactez le support.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/msteams/attach \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_account_id": "6c7d8e9f-0a1b-2c3d-4e5f-60718293a4b5",
    "agent_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "friendly_name": "Support line"
  }'

201 Réponse

json

{
  "phone_number": "+14155550100",
  "agent_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "friendly_name": "Support line",
  "status": "active"
}

POST/integrations/telephony/msteams/calls

Composer un numéro depuis un agent

Passer un appel sortant

Fait sonner to_number et relie l'appelé au pipeline vocal de l'agent. Compose au nom du numéro Teams associé à l'agent lorsqu'il en a un : le destinataire voit votre propre numéro ; un agent sans numéro Teams associé retombe sur le numéro d'appel Teams géré par Aethex (aucune connexion terminée requise pour ce repli). Facturé comme tout appel Aethex et soumis aux contrôles de facturation et de capacité. Nécessite les scopes msteams:write et calls:write.

Corps de la requête

agent_idstring (uuid)requis
L'agent dont le pipeline vocal exécute l'appel. Doit appartenir à votre compte.
to_numberstringrequis
Numéro de destination au format E.164, par exemple +14155550123.

Erreurs

402Paiement requis

Le compte fait l'objet d'un blocage de facturation strict : les appels sont suspendus.

Régularisez le solde ou le moyen de paiement dans la facturation, puis réessayez.

403Numéro en opposition

to_number figure sur la liste d'opposition de votre compte. Le refus intervient avant toute réservation : aucune connexion d'appel ACS n'existe.

Ne réessayez pas. Retirez le numéro de ce que vous appelez, ou levez l'entrée avec POST /suppressions/{id}/release si elle vous appartient.

404Agent introuvable

Aucun agent avec cet agent_id n'existe sur votre compte.

Transmettez un agent_id appartenant à votre compte.

409Agent non prêt

L'agent existe mais n'est pas dans un état lui permettant de prendre un appel.

Vérifiez que l'agent est entièrement configuré et actif, puis réessayez.

422Numéro invalide

to_number n'est pas un numéro de téléphone E.164 valide.

Envoyez la destination au format E.164, par exemple +14155550123.

429Capacité atteinte

Les backends vocaux sont momentanément saturés et n'ont pas pu réserver de créneau.

Réessayez avec un délai progressif. Contactez-nous si cela persiste.

502Erreur du backend d'appel

Le backend d'appel Azure Communication Services a renvoyé une erreur.

Réessayez sous peu. Si le problème persiste, contactez le support.

503Non disponible

L'appel Microsoft Teams n'est pas activé ou pas configuré sur ce déploiement.

Contactez [email protected] pour activer Microsoft Teams sur votre compte.

503Liste d'opposition illisible

La liste d'opposition n'a pas pu être lue ; l'appel a donc été refusé plutôt que passé.

Réessayez après un court délai. La même requête peut être renvoyée sans risque.

Requête

json

curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/msteams/calls \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "to_number": "+14155550123"
  }'

201 Réponse

json

{
  "call_connection_id": "b3d9f1a2-7c4e-4f8a-9b2d-1e2f3a4b5c6d",
  "status": "initiated"
}

DELETE/integrations/telephony/msteams

Supprimer la connexion Teams

Déconnecter Teams

Déconnecte la connexion Microsoft Teams de votre locataire. Idempotent : renvoie toujours 204 No Content, qu'une connexion ait existé ou non. Les numéros associés cessent d'être acheminés vers les agents. Nécessite la portée msteams:write.