Microsoft Teams Phone
App · 20 actions
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.
Actions
| Action | What it does |
|---|---|
| Assign phone number | Give a phone number to a person. |
| Find people | Find people in your organization whose name or email address starts with what you type, with their phone numbers. |
| Get a person's Teams Phone settings | Get one person's phone numbers, whether calling is on, and their calling policies. |
| Get call record | Get one Teams call or meeting: when it was, who took part and, if asked, each leg of the call. |
| Get phone number | Get one phone number's details: its type, who has it, and its emergency location. |
| Get phone number request status | Check whether an assignment or unassignment has finished, and why it failed if it did. |
| Get presence | Get someone's presence in Teams: whether they are available, busy or in a call, and their status message. |
| Get presence of several people | Get the presence of up to 650 people at once, such as everyone who answers a phone line. |
| List call records | List Teams calls and meetings that ended in the last 30 days, with who organized them. |
| List direct routing calls | List calls through your own phone carrier's connection (Direct Routing), with whether each connected and why it failed. |
| 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. |
| List phone numbers | List your organization's phone numbers in Teams and who each is assigned to. |
| List Teams Phone users | List people's Teams Phone settings: their phone numbers, whether calling is on, and their calling policies. |
| Reset my status | Stop showing the status you set, so Teams works your presence out again from your calls, meetings and calendar. |
| 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. |
| Set my status message | Set the message people see on your Teams profile and when they message or call you. |
| 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. |
| Stop showing me as in a call | End the presence Show me as in a call set, before it runs out. |
| Unassign phone number | Take a phone number back from whoever has it, so it can be given to someone else. |
| Update phone number | Change a phone number's emergency location, or route internal calls to it over the phone network. |
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_numbertextRequired - The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
- Person
usertextRequired - Who gets the number.
- Use
assignment_categorytext - How they use it. Leave empty for Primary.One of:
primary,private(Private (incoming calls only)),alternate. - Emergency location id
location_idtext - The id of the emergency location for this number, from the Teams admin center. Leave empty for none.
Outputs
acceptedtrue/false- Always true once Teams has taken the request
operation_idtext- The request's id, for Get phone number request status
telephone_numbertext- The phone number
user_idtext- The id of the person getting it
Example output
{
"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
searchtextRequired - The start of a name or email address.
- Maximum results
max_resultsnumber - The most to return, from 1 to 100. Leave empty for 25.From 1 to 100.
Outputs
countnumber- How many are returned
userslist- The people found
Example output
{
"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
usertextRequired - Whose settings to get.
Outputs
userobject- A person's Teams Phone settings
Example output
{
"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_idtextRequired - The call record's id, from List call records or the New call record trigger.
- Include each leg
include_sessionstrue/false - Also return each leg of the call, with who called whom.Default:
false.
Outputs
call_recordobject- A Teams call or meeting that ended, with who was on it
Example output
{
"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_numbertextRequired - The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
Outputs
numberobject- A phone number your organization has
Example output
{
"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_idtextRequired - The request id Assign phone number or Unassign phone number returned.
Outputs
operationobject- A phone number assignment request
Example output
{
"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
usertext - Whose presence to get. Leave empty for your own.
Outputs
presenceobject- A person's presence in Teams
Example output
{
"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
userslistRequired - The people whose presence to get.
Outputs
countnumber- How many are returned
presenceslist- Each person's presence
Example output
{
"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_timedate and time - The start of the time range, by when calls started. Leave empty for a day before the end.
- Until
end_timedate and time - The end of the time range. Leave empty for now.
- Person
participanttext - Only calls this person took part in. Leave empty for everyone.
- Maximum results
max_resultsnumber - The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.
Outputs
call_recordslist- The call records
countnumber- How many are returned
Example output
{
"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_timedate and time - The start of the time range, by when calls started. Leave empty for a day before the end.
- Until
end_timedate and time - The end of the time range. Leave empty for now.
- Person
usertext - Only this person's calls. Leave empty for everyone.
- Only failed calls
failed_onlytrue/false - Leave out calls that connected.Default:
false. - Maximum results
max_resultsnumber - The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.
Outputs
callslist- The calls, oldest first
countnumber- How many are returned
Example output
{
"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_timedate and time - The start of the time range, by when calls started. Leave empty for a day before the end.
- Until
end_timedate and time - The end of the time range. Leave empty for now.
- Person
usertext - Only this person's calls. Leave empty for everyone.
- Maximum results
max_resultsnumber - The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.
Outputs
callslist- The calls, oldest first
countnumber- How many are returned
Example output
{
"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_typetext - Only numbers of this type. Leave empty for all.One of:
callingPlan(Calling Plan),directRouting(Direct Routing),operatorConnect(Operator Connect). - Assigned to
assignment_statustext - 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_numbertext - Only this number, with its country code. Leave empty for all.
- Maximum results
max_resultsnumber - The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.
Outputs
countnumber- How many are returned
numberslist- The phone numbers
Example output
{
"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_onlytrue/false - Leave out people who can't make or take phone calls in Teams.Default:
false. - Maximum results
max_resultsnumber - The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.
Outputs
countnumber- How many are returned
userslist- Each person's Teams Phone settings
Example output
{
"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
clearedtrue/false- Always true once cleared
user_idtext- Your Microsoft Entra user id
Example output
{
"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
presencetextRequired - 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_aftertext - 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
activitytext- The activity now set
availabilitytext- The availability now set
updatedtrue/false- Always true once set
user_idtext- Your Microsoft Entra user id
Example output
{
"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
messagetextRequired - The status message.
- Clear it at
expires_atdate and time - When to clear it. Leave empty to keep it until you change it.
Outputs
expires_attext- When it clears (ISO 8601, UTC), or empty
messagetext- The message now set
updatedtrue/false- Always true once set
user_idtext- Your Microsoft Entra user id
Example output
{
"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
presencetextRequired - 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)
minutesnumber - How long it lasts unless it is set again, from 5 to 240 minutes. Leave empty for 5.From 5 to 240.
Outputs
activitytext- The activity now set
availabilitytext- The availability now set
minutesnumber- How many minutes it lasts
updatedtrue/false- Always true once set
user_idtext- Your Microsoft Entra user id
Example output
{
"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
clearedtrue/false- Always true once cleared
user_idtext- Your Microsoft Entra user id
was_settrue/false- Whether a workflow presence was in place
Example output
{
"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_numbertextRequired - The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
Outputs
acceptedtrue/false- Always true once Teams has taken the request
operation_idtext- The request's id, for Get phone number request status
previous_user_idtext- The id of who had it, or empty
telephone_numbertext- The phone number
Example output
{
"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_numbertextRequired - The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
- Emergency location id
location_idtext - The id of the new emergency location, from the Teams admin center. Leave empty to keep the current one.
- Clear emergency location
clear_locationtrue/false - Remove the number's emergency location.Default:
false. - Skip internal VoIP
skip_internal_voiptrue/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_numbertext- The phone number
updatedtrue/false- Always true once updated
updated_fieldslist- What changed
Example output
{
"telephone_number": "+12065550100",
"updated": true,
"updated_fields": [
"locationId"
]
}