API Reference

Microsoft Teams Phone

Connect a Microsoft Teams tenant, attach one of your existing Teams numbers to an agent, and place outbound calls over Azure Communication Services. All endpoints live under /integrations/telephony/msteams and authenticate with the X-API-Key header.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 6
Scopes: msteams:readmsteams:writecalls:writephone_numbers:write

POST/integrations/telephony/msteams/connect

Begin Microsoft admin consent

Start Teams connection

Starts the Microsoft admin-consent flow. Returns a consent_url to send your Teams or Global administrator to, and state_expires_in, the number of seconds the link stays valid. No connection is recorded until the administrator approves. Aethex stores only your Microsoft tenant id, never a secret. Requires the msteams:write scope.

Errors

503Not enabled

Microsoft Teams Phone connect is not enabled or not configured on this deployment.

Contact [email protected] to enable Microsoft Teams for your account.

Request

json

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

200 Response

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

Read the linked Teams connection

Get connection

Returns your tenant's active Microsoft Teams connection, including the linked Microsoft tenant (home_tenant_id) and its status. Requires the msteams:read scope.

Errors

404Not connected

Your tenant has no Microsoft Teams connection yet.

Run POST /integrations/telephony/msteams/connect and complete admin consent.

Request

json

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

200 Response

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

Teams numbers linked to Aethex, plus the setup command

List resource accounts

Lists the Teams resource accounts you have linked to Aethex and the number assigned to each. Also returns connect_command: the one-time Microsoft Teams PowerShell line your admin runs to create a linked resource account. The ApplicationId and AcsResourceId are pre-filled in the returned command, so run it verbatim, replacing only YOUR-TEAMS-DOMAIN. Requires the msteams:read scope.

Errors

404Not connected

Your tenant has no Microsoft Teams connection yet.

Run POST /integrations/telephony/msteams/connect and complete admin consent first.

409Reconnect required

The Microsoft session captured at connect has expired.

Call POST /integrations/telephony/msteams/connect again to re-approve.

502Microsoft Graph error

Microsoft returned an error while listing your resource accounts.

Retry shortly. If it persists, contact support.

Request

json

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

200 Response

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

Route a Teams number to an agent

Attach a number

Binds a linked resource account's phone number to one of your agents, so inbound calls to the number are answered by that agent. Idempotent per number: re-attaching re-points the number at the given agent. Requires the msteams:write scope.

Request body

resource_account_idstringrequired
An id returned by GET /integrations/telephony/msteams/resource-accounts.
agent_idstring (uuid)required
The agent that should answer calls to this number. Must belong to your account.
friendly_namestringoptional
Optional label for the number. Defaults to the resource account's display name.

Errors

404Not found

The agent doesn't exist on your account, the resource account isn't linked to Aethex for your tenant, or you have no Teams connection.

Check the agent_id and resource_account_id, and confirm the connection with GET /integrations/telephony/msteams.

409Reconnect required

The Microsoft session captured at connect has expired.

Call POST /integrations/telephony/msteams/connect again to re-approve, then retry.

409Number unavailable

The resource account has no number assigned yet, or the number is already connected to another Aethex account.

Assign a number to the resource account in the Teams Admin Center, or release it from the other account first.

502Microsoft Graph error

Microsoft returned an error while authorizing the number.

Retry shortly. If it persists, contact support.

Request

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 Response

json

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

POST/integrations/telephony/msteams/calls

Dial a number from an agent

Place an outbound call

Rings to_number and bridges the callee into the agent's voice pipeline. Dials on behalf of the agent's attached Teams number when one exists, so the recipient sees your own number; an agent with no Teams number attached falls back to Aethex's managed Teams calling number (no completed connection required for the fallback). Billed like any Aethex call and subject to billing and capacity checks. Requires the msteams:write and calls:write scopes.

Request body

agent_idstring (uuid)required
The agent whose voice pipeline runs the call. Must belong to your account.
to_numberstringrequired
Destination number in E.164, e.g. +14155550123.

Errors

402Payment required

The account has a hard billing block, so calls are paused.

Resolve the balance or payment method in billing, then retry.

403Number suppressed

to_number is on your account's do-not-call list. The refusal happens before anything is reserved, so no ACS call connection exists.

Do not retry. Remove the number from what you dial, or release the entry through POST /suppressions/{id}/release if it is yours to lift.

404Agent not found

No agent with that agent_id exists on your account.

Pass an agent_id that belongs to your account.

409Agent not ready

The agent exists but isn't in a state that can take a call.

Check the agent is fully configured and active, then retry.

422Invalid number

to_number is not a valid E.164 phone number.

Send the destination in E.164 format, e.g. +14155550123.

429At capacity

The voice backends are momentarily saturated and couldn't reserve a slot.

Retry with backoff. Contact us if sustained.

502Calling backend error

The Azure Communication Services calling backend returned an error.

Retry shortly. If it persists, contact support.

503Not available

Microsoft Teams calling is not enabled or not configured on this deployment.

Contact [email protected] to enable Microsoft Teams for your account.

503Suppression list unreadable

The do-not-call list could not be read, so the call was refused rather than placed.

Retry after a short back-off. The same request is safe to send again.

Request

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 Response

json

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

DELETE/integrations/telephony/msteams

Remove the Teams connection

Disconnect Teams

Disconnects your tenant's Microsoft Teams connection. Idempotent: it always returns 204 No Content, whether or not a connection existed. Attached numbers stop routing to agents. Requires the msteams:write scope.