Microsoft Teams Phone

Fonctionnement

Aethex se connecte à Microsoft Teams Phone via Azure Communication Services. Vous conservez votre numéro dans votre propre locataire Microsoft 365. Aethex ne l'achète ni ne le transfère jamais. Un administrateur Teams accorde à Aethex un accès à votre locataire, vous reliez un compte de ressource Teams qui porte l'un de vos numéros existants, puis vous associez ce numéro à un agent. Ensuite, les appels entrants vers le numéro sont pris en charge par l'agent, et vous pouvez passer des appels sortants via la même API. L'agent s'exécute sur le pipeline auto-hébergé de reconnaissance vocale, de modèle de langage et de synthèse vocale d'Aethex.

Prérequis

Dans votre locataire Microsoft 365, il vous faut : une licence Teams Phone (la référence autonome s'appelle Teams Phone Standard ; Microsoft 365 E5 l'inclut) ; un numéro de téléphone sur un compte de ressource Teams, qui porte à la place la licence gratuite Microsoft Teams Phone Resource Account, jamais Teams Phone Standard, que Microsoft ne prend pas en charge sur un compte de ressource ; et un administrateur Teams ou Général pour accorder le consentement et exécuter une commande Teams PowerShell. Pour les appels sortants depuis votre propre numéro, le compte de ressource nécessite en plus une licence Calling Plan Pay-As-You-Go qui lui soit affectée, ainsi qu'une source de financement : soit des Communications Credits, soit l'option Phone services consumption activée pour ce forfait sous Facturation → Vos produits dans le centre d'administration Microsoft 365. Un numéro Direct Routing n'exige ni l'un ni l'autre. Depuis le 1er novembre 2025, un Calling Plan seul ne couvre que l'entrant. Côté Aethex : une clé API dotée des portées msteams:read et msteams:write, et un agent pour répondre aux appels (créez-en un depuis le tableau de bord ou l'API Agents).

Ce que fait votre administrateur Teams (une seule fois)

Tout ce qui suit se fait une seule fois, dans votre propre locataire Microsoft 365. Aethex n'achète, ne porte ni ne détient jamais votre numéro, et vos utilisateurs Teams ne sont pas affectés : l'agent répond sur un compte de ressource, une identité sous licence destinée aux applications vocales plutôt qu'à une personne.1. Licencier le locataire. Il vous faut Teams Phone (seul ou via E5). Pour que l'agent émette des appels, il faut aussi un Calling Plan Pay-As-You-Go pour votre zone, ainsi qu'une source de financement : soit activer Phone services consumption pour ce forfait sous Facturation → Vos produits, soit acheter des Communications Credits et maintenir un solde positif. Depuis le 1er novembre 2025, un Calling Plan seul ne couvre que l'entrant.2. Acheter la licence gratuite de compte de ressource. Place de marché → Tous les produits → Microsoft Teams Phone Resource Account. Elle est gratuite, mais la commande doit tout de même être passée.3. Obtenir un numéro de service. Centre d'administration Teams → Voix → Numéros de téléphone → Ajouter. Choisissez un numéro de service, pas un numéro d'utilisateur (abonné) : un compte de ressource ne peut pas détenir un numéro d'utilisateur. Une adresse d'urgence dans le pays du numéro vous sera demandée.4. Créer le compte de ressource avec la commande PowerShell fournie par Aethex (section suivante). Le centre d'administration Teams ne peut pas effectuer cette étape, car le compte doit être créé avec l'identifiant d'application Aethex.5. Licencier le compte de ressource : la licence gratuite Teams Phone Resource Account, plus le Calling Plan Pay-As-You-Go s'il doit émettre des appels. Définissez son emplacement d'utilisation sur le pays du numéro. Ne lui attribuez pas Teams Phone Standard : Microsoft ne le prend pas en charge sur un compte de ressource et cela le rend inopérant.6. Affecter le numéro et le relier à Aethex, puis approuver le lien de consentement. Ces deux étapes sont une commande unique et un simple clic, détaillées dans la section suivante.

Connectez votre numéro Teams

Tout le parcours se déroule via l'API REST, plus un clic de consentement administrateur et une commande PowerShell. Définissez AETHEX_API_KEY dans votre shell, puis suivez les étapes dans l'ordre.

1. 01

   Obtenez une clé API avec les portées Teams

   Créez une clé API dotée des portées msteams:read et msteams:write. Les nouvelles clés les incluent par défaut : une clé fraîchement créée fonctionne telle quelle. Exportez-la sous AETHEX_API_KEY pour les appels ci-dessous.

2. 02

   Lancez le consentement administrateur

   Appelez POST /connect. La réponse renvoie une consent_url et state_expires_in (en secondes). Envoyez votre administrateur Teams ou Général vers la consent_url, où il se connecte à Microsoft et approuve l'accès d'Aethex. Le lien est à usage unique et expire une fois state_expires_in écoulé. Après l'approbation, Microsoft affiche une courte page de confirmation qu'il peut fermer, et la connexion est enregistrée pour votre locataire. Aethex ne stocke que l'identifiant de votre locataire Microsoft, jamais un mot de passe ni un secret.

   Démarrez la connexion

   bash

   curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/msteams/connect \
     -H "X-API-Key: $AETHEX_API_KEY"
   
   # Response: send your Teams admin to consent_url; it is valid for state_expires_in seconds.
   # {
   #   "consent_url": "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?client_id=...&state=...",
   #   "state_expires_in": 600
   # }

3. 03

   Reliez un compte de ressource Teams

   Appelez GET /resource-accounts pour lire connect_command, une ligne Microsoft Teams PowerShell prête à l'emploi. Votre administrateur Teams l'exécute une fois pour créer un compte de ressource relié à Aethex, puis affecte l'un de vos numéros Teams existants à ce compte dans le Centre d'administration Teams. Deux points imposés par Microsoft : le compte de ressource doit porter la licence gratuite Microsoft Teams Phone Resource Account, jamais Teams Phone Standard, non prise en charge sur les comptes de ressource et qui les rend inopérants ; et le numéro doit être un numéro de service, pas un numéro d'utilisateur (abonné). Les valeurs ApplicationId et AcsResourceId de la commande arrivent pré-remplies, donc copiez la chaîne telle quelle et remplacez uniquement YOUR-TEAMS-DOMAIN par le domaine de votre locataire.

   Lisez et exécutez la commande de connexion

   bash

   # 1. Read the ready-to-run PowerShell line from your connection.
   curl https://api.aethexai.com/api/v1/integrations/telephony/msteams/resource-accounts \
     -H "X-API-Key: $AETHEX_API_KEY"
   
   # 2. In an elevated Microsoft Teams PowerShell session, paste the "connect_command"
   #    string exactly as returned (ApplicationId and AcsResourceId arrive filled in),
   #    replacing YOUR-TEAMS-DOMAIN with your tenant domain:
   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>'
   
   # 3. In the Teams Admin Center, assign one of your existing Teams SERVICE numbers
   #    (licensed with the free Teams Phone Resource Account SKU, never Teams Phone Standard) to that resource account.

4. 04

   Confirmez que le numéro est relié

   Appelez à nouveau GET /resource-accounts. Une fois que Microsoft a terminé le provisionnement (généralement quelques minutes), le compte apparaît avec son phone_number affecté au format E.164. Notez l'id du compte, que vous transmettez à attach à l'étape suivante.

   Compte de ressource avec son numéro

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

5. 05

   Associez le numéro à un agent

   Appelez POST /attach avec l'id du compte de ressource et l'agent_id qui doit répondre au numéro. Aethex autorise le numéro dans sa ressource d'appel et achemine les appels entrants vers votre agent. Réassocier le même numéro le repointe simplement vers un autre agent.

   Liez le numéro à un agent

   bash

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

6. 06

   Passez et recevez des appels

   Les appels entrants vers le numéro associé atteignent désormais l'agent automatiquement, sans configuration supplémentaire. Pour appeler, appelez POST /calls avec un agent_id et un to_number de destination. La réponse renvoie un call_connection_id que vous pouvez utiliser pour corréler l'appel.

   Passez un appel sortant

   bash

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

Authentification et portées

Authentifiez chaque requête avec votre clé API dans l'en-tête X-API-Key. Les endpoints Microsoft Teams exigent deux portées : msteams:read pour consulter la connexion et lister les comptes de ressource, et msteams:write pour connecter, associer un numéro, passer un appel et déconnecter. Les deux font partie du lot de portées par défaut : les clés nouvellement créées les portent déjà. Consultez Portées pour le modèle complet.

Appels entrants et sortants

Entrant : une fois un numéro associé, les appels vers celui-ci sont pris en charge par l'agent auquel vous l'avez lié. Sortant : POST /calls fait sonner la destination et relie l'appelé au pipeline vocal de l'agent. Les appels sortants sont facturés comme tout autre appel Aethex et passent par les mêmes contrôles d'admission : un blocage de facturation strict ou une limite de capacité est signalé avant que l'appel ne soit passé.

Erreurs courantes

Les endpoints Teams renvoient des codes de statut HTTP standard. Voici ceux que vous rencontrerez le plus souvent ; la référence de l'API liste les erreurs par endpoint.

Si quelque chose ne fonctionne pas

La connexion à Teams PowerShell échoue avec `AADSTS530035`. Votre locataire bloque le flux de connexion par code d'appareil, généralement parce que les paramètres de sécurité par défaut sont activés. Le module Teams PowerShell bascule sur ce flux sous macOS et Linux : exécutez-le depuis Windows, qui utilise un autre flux, ou désactivez temporairement les paramètres de sécurité par défaut, attendez une quinzaine de minutes que le changement prenne effet, connectez-vous, puis réactivez-les.« Vous ne pouvez pas attribuer des licences contenant ces services en conflit. » Teams Phone Standard est coché en plus de la licence de compte de ressource. Décochez Teams Phone Standard.Le numéro refuse de s'affecter au compte de ressource. Soit les licences ne se sont pas encore propagées, soit le numéro est un numéro d'utilisateur et non de service. Seuls les numéros de service peuvent être affectés à un compte de ressource.L'entrant fonctionne mais les appels sortants échouent. Le compte de ressource n'a pas la licence Calling Plan Pay-As-You-Go, ou le locataire n'a pas de source de financement. Vérifiez que le forfait est bien attribué au compte de ressource lui-même, et que Phone services consumption est activé ou que les Communications Credits ont un solde positif.Les appelants entendent que le numéro est indisponible. Le compte de ressource n'est pas encore entièrement relié. Réexécutez les commandes de liaison et de synchronisation de la section précédente, et vérifiez que le compte affiche un numéro de téléphone et Enterprise Voice activé.

Référence de l'API

Pour chaque endpoint, paramètre et champ de réponse, consultez la référence de l'API Microsoft Teams Phone.