# Microsoft Teams Phone

> See who is available or on a call, set your Teams status, manage phone numbers, read call history, and start workflows on new calls and presence changes.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/microsoft-teams-phone

## Actions

### Assign phone number

Give a phone number to a person. Teams finishes it within a few minutes; Get phone number request status says when. Needs a Teams admin.

**Inputs**

- Phone number (`telephone_number`, text, required): The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
- Person (`user`, text, required): Who gets the number.
- Use (`assignment_category`, text): How they use it. Leave empty for Primary. One of: `primary`, `private` (Private (incoming calls only)), `alternate`.
- Emergency location id (`location_id`, text): The id of the emergency location for this number, from the Teams admin center. Leave empty for none.

**Outputs**

- `accepted` (true/false): Always true once Teams has taken the request
- `operation_id` (text): The request's id, for Get phone number request status
- `telephone_number` (text): The phone number
- `user_id` (text): The id of the person getting it

**Example output**

```json
{
  "accepted": true,
  "operation_id": "QXNzaWdubWVudHw2Y2E4Yjc0Ni00YzgxLTRhY2EtOTUyNi1jZmNjNGRiYWYyMmI",
  "telephone_number": "+12065550100",
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}
```

### Find people

Find people in your organization whose name or email address starts with what you type, with their phone numbers.

**Inputs**

- Name or email (`search`, text, required): The start of a name or email address.
- Maximum results (`max_results`, number): The most to return, from 1 to 100. Leave empty for 25. From 1 to 100.

**Outputs**

- `count` (number): How many are returned
- `users` (list): The people found

**Example output**

```json
{
  "count": 1,
  "users": [
    {
      "businessPhones": [
        "+12065550100"
      ],
      "displayName": "Adele Vance",
      "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "jobTitle": "Deputy Clerk",
      "mail": "adelev@contoso.com",
      "mobilePhone": "",
      "userPrincipalName": "adelev@contoso.com"
    }
  ]
}
```

### Get a person's Teams Phone settings

Get one person's phone numbers, whether calling is on, and their calling policies. Needs a Teams admin.

**Inputs**

- Person (`user`, text, required): Whose settings to get.

**Outputs**

- `user` (object): A person's Teams Phone settings

**Example output**

```json
{
  "user": {
    "accountType": "user",
    "createdDateTime": "2025-01-07T09:08:50.9115993Z",
    "featureTypes": [
      "Teams",
      "PhoneSystem",
      "CallingPlan"
    ],
    "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "isEnterpriseVoiceEnabled": true,
    "modifiedDateTime": "2025-01-07T09:08:50.9115993Z",
    "policies": [
      {
        "assignmentType": "group",
        "displayName": "AllOn",
        "policyType": "TeamsCallingPolicy"
      }
    ],
    "primary_phone_number": "+12065550100",
    "telephoneNumbers": [
      {
        "assignmentCategory": "primary",
        "telephoneNumber": "+12065550100"
      }
    ],
    "userPrincipalName": "adelev@contoso.com"
  }
}
```

### Get call record

Get one Teams call or meeting: when it was, who took part and, if asked, each leg of the call. Needs the CallRecords.Read.All application permission (see the connect steps).

**Inputs**

- Call record id (`call_record_id`, text, required): The call record's id, from List call records or the New call record trigger.
- Include each leg (`include_sessions`, true/false): Also return each leg of the call, with who called whom. Default: `false`.

**Outputs**

- `call_record` (object): A Teams call or meeting that ended, with who was on it

**Example output**

```json
{
  "call_record": {
    "endDateTime": "2026-11-03T18:52:46.7640013Z",
    "id": "e523d2ed-2966-4b6b-925b-754a88034cc5",
    "joinWebUrl": "",
    "lastModifiedDateTime": "2026-11-03T19:00:24.582757Z",
    "modalities": [
      "audio"
    ],
    "organizer_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "organizer_name": "Adele Vance",
    "participants": [
      {
        "displayName": "Adele Vance",
        "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
        "kind": "user"
      },
      {
        "displayName": "Owen Franklin",
        "id": "66825e03-7ef5-42da-9069-724602c31f6b",
        "kind": "user"
      }
    ],
    "sessions": [
      {
        "callee_name": "Owen Franklin",
        "caller_name": "Adele Vance",
        "endDateTime": "2026-11-03T18:52:46.7640013Z",
        "id": "e523d2ed-2966-4b6b-925b-754a88034cc5",
        "modalities": [
          "audio"
        ],
        "startDateTime": "2026-11-03T18:52:21.2169889Z"
      }
    ],
    "startDateTime": "2026-11-03T18:52:21.2169889Z",
    "type": "peerToPeer",
    "version": 1
  }
}
```

### Get phone number

Get one phone number's details: its type, who has it, and its emergency location. Needs a Teams admin.

**Inputs**

- Phone number (`telephone_number`, text, required): The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.

**Outputs**

- `number` (object): A phone number your organization has

**Example output**

```json
{
  "number": {
    "activationState": "activated",
    "assignmentCategory": "primary",
    "assignmentStatus": "userAssigned",
    "assignmentTargetId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "capabilities": [
      "userAssignment"
    ],
    "city": "Seattle",
    "civicAddressId": "",
    "id": "YmMyNjMyZTMtNzUwYy00N2Q3LWFlYWUtOWZlZTAzNWJjMGM3fCsxMjAyMzQ1Njc4OQ",
    "isoCountryCode": "US",
    "locationId": "",
    "numberSource": "online",
    "numberType": "callingPlan",
    "operatorId": "7a205197-8e59-487d-b9fa-3fc1b108f1e5",
    "portInStatus": "",
    "reverseNumberLookupOptions": [],
    "supportedCustomerActions": [
      "locationUpdate"
    ],
    "telephoneNumber": "+12065550100"
  }
}
```

### Get phone number request status

Check whether an assignment or unassignment has finished, and why it failed if it did.

**Inputs**

- Request id (`operation_id`, text, required): The request id Assign phone number or Unassign phone number returned.

**Outputs**

- `operation` (object): A phone number assignment request

**Example output**

```json
{
  "operation": {
    "createdDateTime": "2026-11-03T22:03:26Z",
    "id": "QXNzaWdubWVudHw2Y2E4Yjc0Ni00YzgxLTRhY2EtOTUyNi1jZmNjNGRiYWYyMmI",
    "numbers": [
      {
        "resourceLocation": "https://graph.microsoft.com/v1.0/admin/teams/telephoneNumberManagement/numberAssignments/N2EyMDUxOTctOGU1OS00ODdkLWI5ZmEtM2ZjMWIxMDhmMWU1fCsxMjA2MTIzNDU2Nw",
        "status": "succeeded",
        "statusDetail": ""
      }
    ],
    "status": "succeeded"
  }
}
```

### Get presence

Get someone's presence in Teams: whether they are available, busy or in a call, and their status message.

**Inputs**

- Person (`user`, text): Whose presence to get. Leave empty for your own.

**Outputs**

- `presence` (object): A person's presence in Teams

**Example output**

```json
{
  "presence": {
    "activity": "InACall",
    "availability": "Busy",
    "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "is_out_of_office": false,
    "out_of_office_message": "",
    "sequenceNumber": "A0129311063",
    "status_message": "On the clerk's office line until noon"
  }
}
```

### Get presence of several people

Get the presence of up to 650 people at once, such as everyone who answers a phone line.

**Inputs**

- People (`users`, list, required): The people whose presence to get.

**Outputs**

- `count` (number): How many are returned
- `presences` (list): Each person's presence

**Example output**

```json
{
  "count": 1,
  "presences": [
    {
      "activity": "InACall",
      "availability": "Busy",
      "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "is_out_of_office": false,
      "out_of_office_message": "",
      "sequenceNumber": "A0129311063",
      "status_message": "On the clerk's office line until noon"
    }
  ]
}
```

### List call records

List Teams calls and meetings that ended in the last 30 days, with who organized them. Needs the CallRecords.Read.All application permission (see the connect steps).

**Inputs**

- From (`start_time`, date and time): The start of the time range, by when calls started. Leave empty for a day before the end.
- Until (`end_time`, date and time): The end of the time range. Leave empty for now.
- Person (`participant`, text): Only calls this person took part in. Leave empty for everyone.
- Maximum results (`max_results`, number): The most to return, from 1 to 1000. Leave empty for 200. From 1 to 1000.

**Outputs**

- `call_records` (list): The call records
- `count` (number): How many are returned

**Example output**

```json
{
  "call_records": [
    {
      "endDateTime": "2026-11-03T18:52:46.7640013Z",
      "id": "e523d2ed-2966-4b6b-925b-754a88034cc5",
      "joinWebUrl": "",
      "lastModifiedDateTime": "2026-11-03T19:00:24.582757Z",
      "modalities": [
        "audio"
      ],
      "organizer_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "organizer_name": "Adele Vance",
      "startDateTime": "2026-11-03T18:52:21.2169889Z",
      "type": "peerToPeer",
      "version": 1
    }
  ],
  "count": 1
}
```

### List direct routing calls

List calls through your own phone carrier's connection (Direct Routing), with whether each connected and why it failed. Needs the CallRecords.Read.All application permission (see the connect steps).

**Inputs**

- From (`start_time`, date and time): The start of the time range, by when calls started. Leave empty for a day before the end.
- Until (`end_time`, date and time): The end of the time range. Leave empty for now.
- Person (`user`, text): Only this person's calls. Leave empty for everyone.
- Only failed calls (`failed_only`, true/false): Leave out calls that connected. Default: `false`.
- Maximum results (`max_results`, number): The most to return, from 1 to 1000. Leave empty for 200. From 1 to 1000.

**Outputs**

- `calls` (list): The calls, oldest first
- `count` (number): How many are returned

**Example output**

```json
{
  "calls": [
    {
      "callEndSubReason": 540000,
      "callType": "ByotIn",
      "calleeNumber": "+12065550100",
      "callerNumber": "+12065550199",
      "correlationId": "c98e1515-a937-4b81-b8a8-3992afde64e0",
      "duration": 5,
      "endDateTime": "2026-11-03T15:00:30.105Z",
      "failureDateTime": "0001-01-01T00:00:00Z",
      "finalSipCode": 0,
      "finalSipCodePhrase": "BYE",
      "id": "9e8bba57-dc14-533a-a7dd-f0da6575eed1",
      "inviteDateTime": "2026-11-03T15:00:21.949Z",
      "mediaBypassEnabled": false,
      "mediaPathLocation": "USWE",
      "signalingLocation": "USWE",
      "startDateTime": "2026-11-03T15:00:25.105Z",
      "successfulCall": true,
      "trunkFullyQualifiedDomainName": "sbc1.contoso.com",
      "userDisplayName": "Adele Vance",
      "userId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "userPrincipalName": "adelev@contoso.com"
    }
  ],
  "count": 1
}
```

### List phone network calls

List calls people made and received over the phone network with Calling Plans or Operator Connect, with numbers, length and cost. Needs the CallRecords.Read.All application permission (see the connect steps).

**Inputs**

- From (`start_time`, date and time): The start of the time range, by when calls started. Leave empty for a day before the end.
- Until (`end_time`, date and time): The end of the time range. Leave empty for now.
- Person (`user`, text): Only this person's calls. Leave empty for everyone.
- Maximum results (`max_results`, number): The most to return, from 1 to 1000. Leave empty for 200. From 1 to 1000.

**Outputs**

- `calls` (list): The calls, oldest first
- `count` (number): How many are returned

**Example output**

```json
{
  "calls": [
    {
      "callDurationSource": "microsoft",
      "callId": "1835317186_112562680@61.221.3.176",
      "callType": "user_in",
      "calleeNumber": "+12065550100",
      "callerNumber": "+12065550199",
      "charge": 0,
      "conferenceId": "",
      "connectionCharge": 0,
      "currency": "USD",
      "destinationContext": "",
      "destinationName": "United States",
      "duration": 219,
      "endDateTime": "2026-11-03T15:03:47.2589935Z",
      "id": "9c4984c7-6c3c-427d-a30c-bd0b2eacee90",
      "inventoryType": "Subscriber",
      "licenseCapability": "MCOPSTNU",
      "operator": "Microsoft",
      "startDateTime": "2026-11-03T15:00:08.2589935Z",
      "tenantCountryCode": "US",
      "usageCountryCode": "US",
      "userDisplayName": "Adele Vance",
      "userId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "userPrincipalName": "adelev@contoso.com"
    }
  ],
  "count": 1
}
```

### List phone numbers

List your organization's phone numbers in Teams and who each is assigned to. Needs a Teams admin.

**Inputs**

- Number type (`number_type`, text): Only numbers of this type. Leave empty for all. One of: `callingPlan` (Calling Plan), `directRouting` (Direct Routing), `operatorConnect` (Operator Connect).
- Assigned to (`assignment_status`, text): Only numbers in this state, such as Not assigned to find a free one. Leave empty for all. One of: `unassigned` (Not assigned), `userAssigned` (Assigned to a person), `conferenceAssigned` (Assigned to audio conferencing), `voiceApplicationAssigned` (Assigned to a call queue or auto attendant), `thirdPartyAppAssigned` (Assigned to a third-party app), `policyAssigned` (Assigned to a shared calling policy).
- Phone number (`telephone_number`, text): Only this number, with its country code. Leave empty for all.
- Maximum results (`max_results`, number): The most to return, from 1 to 1000. Leave empty for 200. From 1 to 1000.

**Outputs**

- `count` (number): How many are returned
- `numbers` (list): The phone numbers

**Example output**

```json
{
  "count": 1,
  "numbers": [
    {
      "activationState": "activated",
      "assignmentCategory": "primary",
      "assignmentStatus": "userAssigned",
      "assignmentTargetId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "capabilities": [
        "userAssignment"
      ],
      "city": "Seattle",
      "civicAddressId": "",
      "id": "YmMyNjMyZTMtNzUwYy00N2Q3LWFlYWUtOWZlZTAzNWJjMGM3fCsxMjAyMzQ1Njc4OQ",
      "isoCountryCode": "US",
      "locationId": "",
      "numberSource": "online",
      "numberType": "callingPlan",
      "operatorId": "7a205197-8e59-487d-b9fa-3fc1b108f1e5",
      "portInStatus": "",
      "reverseNumberLookupOptions": [],
      "supportedCustomerActions": [
        "locationUpdate"
      ],
      "telephoneNumber": "+12065550100"
    }
  ]
}
```

### List Teams Phone users

List people's Teams Phone settings: their phone numbers, whether calling is on, and their calling policies. Needs a Teams admin.

**Inputs**

- Only people with calling on (`voice_enabled_only`, true/false): Leave out people who can't make or take phone calls in Teams. Default: `false`.
- Maximum results (`max_results`, number): The most to return, from 1 to 1000. Leave empty for 200. From 1 to 1000.

**Outputs**

- `count` (number): How many are returned
- `users` (list): Each person's Teams Phone settings

**Example output**

```json
{
  "count": 1,
  "users": [
    {
      "accountType": "user",
      "createdDateTime": "2025-01-07T09:08:50.9115993Z",
      "featureTypes": [
        "Teams",
        "PhoneSystem",
        "CallingPlan"
      ],
      "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "isEnterpriseVoiceEnabled": true,
      "modifiedDateTime": "2025-01-07T09:08:50.9115993Z",
      "policies": [
        {
          "assignmentType": "group",
          "displayName": "AllOn",
          "policyType": "TeamsCallingPolicy"
        }
      ],
      "primary_phone_number": "+12065550100",
      "telephoneNumbers": [
        {
          "assignmentCategory": "primary",
          "telephoneNumber": "+12065550100"
        }
      ],
      "userPrincipalName": "adelev@contoso.com"
    }
  ]
}
```

### Reset my status

Stop showing the status you set, so Teams works your presence out again from your calls, meetings and calendar.

**Inputs**: None.

**Outputs**

- `cleared` (true/false): Always true once cleared
- `user_id` (text): Your Microsoft Entra user id

**Example output**

```json
{
  "cleared": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}
```

### Set my status

Set the status you show in Teams, as choosing it in Teams does: available, busy, do not disturb, be right back, away or offline.

**Inputs**

- Status (`presence`, text, required): The status to show. One of: `Available/Available` (Available), `Busy/Busy` (Busy), `DoNotDisturb/DoNotDisturb` (Do not disturb), `BeRightBack/BeRightBack` (Be right back), `Away/Away` (Appear away), `Offline/OffWork` (Appear offline).
- For (`expires_after`, text): How long to keep it. Leave empty for Teams' default: a day for busy or do not disturb, a week for the others. One of: `PT1H` (1 hour), `PT2H` (2 hours), `PT4H` (4 hours), `PT8H` (8 hours), `PT24H` (1 day), `PT168H` (1 week).

**Outputs**

- `activity` (text): The activity now set
- `availability` (text): The availability now set
- `updated` (true/false): Always true once set
- `user_id` (text): Your Microsoft Entra user id

**Example output**

```json
{
  "activity": "DoNotDisturb",
  "availability": "DoNotDisturb",
  "updated": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}
```

### Set my status message

Set the message people see on your Teams profile and when they message or call you.

**Inputs**

- Message (`message`, text, required): The status message.
- Clear it at (`expires_at`, date and time): When to clear it. Leave empty to keep it until you change it.

**Outputs**

- `expires_at` (text): When it clears (ISO 8601, UTC), or empty
- `message` (text): The message now set
- `updated` (true/false): Always true once set
- `user_id` (text): Your Microsoft Entra user id

**Example output**

```json
{
  "expires_at": "2026-11-06T17:00:00Z",
  "message": "On the clerk's office line until noon",
  "updated": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}
```

### Show me as in a call

Tell Teams you are busy somewhere else for a while, such as on a call in another phone system. Teams combines it with your other activity.

**Inputs**

- Presence (`presence`, text, required): What to show. One of: `Available/Available` (Available), `Busy/InACall` (Busy, in a call), `Busy/InAConferenceCall` (Busy, in a conference call), `Away/Away` (Away), `DoNotDisturb/Presenting` (Do not disturb, presenting).
- For (minutes) (`minutes`, number): How long it lasts unless it is set again, from 5 to 240 minutes. Leave empty for 5. From 5 to 240.

**Outputs**

- `activity` (text): The activity now set
- `availability` (text): The availability now set
- `minutes` (number): How many minutes it lasts
- `updated` (true/false): Always true once set
- `user_id` (text): Your Microsoft Entra user id

**Example output**

```json
{
  "activity": "InACall",
  "availability": "Busy",
  "minutes": 30,
  "updated": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}
```

### Stop showing me as in a call

End the presence Show me as in a call set, before it runs out.

**Inputs**: None.

**Outputs**

- `cleared` (true/false): Always true once cleared
- `user_id` (text): Your Microsoft Entra user id
- `was_set` (true/false): Whether a workflow presence was in place

**Example output**

```json
{
  "cleared": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
  "was_set": true
}
```

### Unassign phone number

Take a phone number back from whoever has it, so it can be given to someone else. Needs a Teams admin.

**Inputs**

- Phone number (`telephone_number`, text, required): The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.

**Outputs**

- `accepted` (true/false): Always true once Teams has taken the request
- `operation_id` (text): The request's id, for Get phone number request status
- `previous_user_id` (text): The id of who had it, or empty
- `telephone_number` (text): The phone number

**Example output**

```json
{
  "accepted": true,
  "operation_id": "QXNzaWdubWVudHw2Y2E4Yjc0Ni00YzgxLTRhY2EtOTUyNi1jZmNjNGRiYWYyMmI",
  "previous_user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
  "telephone_number": "+12065550100"
}
```

### Update phone number

Change a phone number's emergency location, or route internal calls to it over the phone network. Needs a Teams admin.

**Inputs**

- Phone number (`telephone_number`, text, required): The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
- Emergency location id (`location_id`, text): The id of the new emergency location, from the Teams admin center. Leave empty to keep the current one.
- Clear emergency location (`clear_location`, true/false): Remove the number's emergency location. Default: `false`.
- Skip internal VoIP (`skip_internal_voip`, true/false): Send calls from inside your organization to this number over the phone network instead of Teams. Turn it off again in the Teams admin center. Default: `false`.

**Outputs**

- `telephone_number` (text): The phone number
- `updated` (true/false): Always true once updated
- `updated_fields` (list): What changed

**Example output**

```json
{
  "telephone_number": "+12065550100",
  "updated": true,
  "updated_fields": [
    "locationId"
  ]
}
```
