Edit

Share via

Synchronize service representative presence status across multiple systems

Presence APIs provide methods to access and update customer service representative (service representative or representative) availability information across multiple systems. You can synchronize service representatives' presence status to avoid overbooking and ensure synchronization across platforms.

Prerequisites

Before you start, make sure you have the following:

  • A license for Dynamics 365 Contact Center.
  • Omnichannel agent or Omnichannel Supervisor role for the service representatives whose presence status you want to sync.
  • A third-party application that you want to integrate with, such as Teams. The application must be allowlisted in Dataverse to access APIs and entities.
  • A middleware system that can pass messages between Dynamics 365 Contact Center, Dynamics 365 Customer Service and the other application.
  • A service representative dictionary in the middleware that maps the service representatives' IDs in both systems.

Set up a webhook for representative presence changes

A webhook allows an external service to start a particular runbook in Azure Automation through a single HTTP request. To get notified of service representative presence changes or new service representatives, you can set up a webhook for the msdyn_agentstatus entity, which stores the service representative's status updates.

  1. Create and register a webhook using the plug-in registration tool.
  2. Register a step for the WebHook for updating a service representative's presence status or adding a new service representative with the following parameters:
    • Primary Entity: msdyn_agentstatus
    • Execution Mode: Synchronous
    • Deployment: Server

    Note

    If you want to capture presence changes only, we recommend that you set Filtering attributes to current presence to improve performance.

Use the webhook

When the service representative's presence status changes or a new service representative is added in the application, the webhook sends a notification to the external service with the updated information. You can use this information to sync the service representative's presence status in the other system. From the webhook response, you can get the msdyn_agentid for which the presence changed to msdyn_currentpresenceid.

By default, the out-of-the-box presence statuses mapped to the following presence id.

Presence Status Presence Id
Available f523f628-c07a-e811-8162-000d3aa11f50
Busy efdeb843-c07a-e811-8162-000d3aa11f50
Busy DND 08971864-c07a-e811-8162-000d3aa11f50
Offline 70139190-c07a-e811-8162-000d3aa11f50
Away 3dacae76-c07a-e811-8162-000d3aa11f50

The following sections provide examples of the JSON payload for when the service representative presence is modified and when a new service representative is added.

{
   "BusinessUnitId":"a3c20b02-4e38-ef11-a315-000d3a5a54dc",
   "CorrelationId":"dddd3333-ee44-5555-66ff-777777aaaaaa",
   "Depth":1,
   "InitiatingUserAgent":"Microsoft.CCaaS.AssignmentEngineVNext.AssignmentEngineVNext (DataverseSvcClient:1.1.0.11)",
   "InitiatingUserAzureActiveDirectoryObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
   "InitiatingUserId":"d89254ff-9438-ef11-a315-000d3a5a54dc",
   "InputParameters":[
      {
         "key":"Target",
         "value":{
            "__type":"Entity:http://schemas.microsoft.com/xrm/2011/Contracts",
            "Attributes":[
               {
                  "key":"modifiedby",
                  "value":{
                     "__type":"EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
                     "Id":"d89254ff-9438-ef11-a315-000d3a5a54dc",
                     "KeyAttributes":[

                     ],
                     "LogicalName":"systemuser",
                     "Name":null,
                     "RowVersion":null
                  }
               },
               {
                  "key":"msdyn_isagentloggedin",
                  "value":true
               },
               {
                  "key":"msdyn_currentpresenceid",
                  "value":{
                     "__type":"EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
                     "Id":"efdeb843-c07a-e811-8162-000d3aa11f50",
                     "KeyAttributes":[

                     ],
                     "LogicalName":"msdyn_presence",
                     "Name":null,
                     "RowVersion":null
                  }
               },
               {
                  "key":"modifiedon",
                  "value":"\/Date(1722582039000)\/"
               },
               {
                  "key":"modifiedonbehalfby",
                  "value":null
               },
               {
                  "key":"msdyn_availableunitscapacity",
                  "value":100
               },
               {
                  "key":"msdyn_agentstatusid",
                  "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
               },
               {
                  "key":"msdyn_capacitymodifiedon",
                  "value":"\/Date(1722581814000)\/"
               },
               {
                  "key":"msdyn_presencemodifiedon",
                  "value":"\/Date(1722582038000)\/"
               },
               {
                  "key":"msdyn_isblockedbysomeprofile",
                  "value":false
               },
               {
                  "key":"msdyn_presencemodifiedby",
                  "value":"AGENT"
               },
               {
                  "key":"msdyn_agentid",
                  "value":{
                     "__type":"EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
                     "Id":"97c90b02-4e38-ef11-a315-000d3a5a54dc",
                     "KeyAttributes":[

                     ],
                     "LogicalName":"systemuser",
                     "Name":null,
                     "RowVersion":null
                  }
               },
               {
                  "key":"timezoneruleversionnumber",
                  "value":4
               }
            ],
            "EntityState":null,
            "FormattedValues":[

            ],
            "Id":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "KeyAttributes":[

            ],
            "LogicalName":"msdyn_agentstatus",
            "RelatedEntities":[

            ],
            "RowVersion":"5948260"
         }
      }
   ],
   "IsExecutingOffline":false,
   "IsInTransaction":false,
   "IsOfflinePlayback":false,
   "IsolationMode":1,
   "MessageName":"Update",
   "Mode":1,
   "OperationCreatedOn":"\/Date(1722582039000+0000)\/",
   "OperationId":"1a14c3ec-9c50-ef11-bfe3-00224802dbb1",
   "OrganizationId":"66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
   "OrganizationName":"unq6042beb1a93aef118e4b00224802c",
   "OutputParameters":[

   ],
   "OwningExtension":{
      "Id":"8ff4bda5-9d4e-ef11-bfe3-00224802dbb1",
      "KeyAttributes":[

      ],
      "LogicalName":"sdkmessageprocessingstep",
      "Name":null,
      "RowVersion":null
   },
   "ParentContext":{
      "BusinessUnitId":"a3c20b02-4e38-ef11-a315-000d3a5a54dc",
      "CorrelationId":"dddd3333-ee44-5555-66ff-777777aaaaaa",
      "Depth":1,
      "InitiatingUserAgent":"Microsoft.CCaaS.AssignmentEngineVNext.AssignmentEngineVNext (DataverseSvcClient:1.1.0.11)",
      "InitiatingUserAzureActiveDirectoryObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "InitiatingUserId":"d89254ff-9438-ef11-a315-000d3a5a54dc",
      "InputParameters":[
         {
            "key":"Target",
            "value":{
               "__type":"Entity:http://schemas.microsoft.com/xrm/2011/Contracts",
               "Attributes":[
                  {
                     "key":"msdyn_agentstatusid",
                     "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
                  },
                  {
                     "key":"msdyn_availableunitscapacity",
                     "value":100
                  },
                  {
                     "key":"msdyn_currentpresenceid",
                     "value":{
                        "__type":"EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
                        "Id":"efdeb843-c07a-e811-8162-000d3aa11f50",
                        "KeyAttributes":[

                        ],
                        "LogicalName":"msdyn_presence",
                        "Name":null,
                        "RowVersion":null
                     }
                  },
                  {
                     "key":"msdyn_capacitymodifiedon",
                     "value":"\/Date(1722581814000)\/"
                  },
                  {
                     "key":"msdyn_presencemodifiedby",
                     "value":"AGENT"
                  },
                  {
                     "key":"msdyn_presencemodifiedon",
                     "value":"\/Date(1722582038000)\/"
                  },
                  {
                     "key":"msdyn_isblockedbysomeprofile",
                     "value":false
                  },
                  {
                     "key":"msdyn_isagentloggedin",
                     "value":true
                  },
                  {
                     "key":"msdyn_agentid",
                     "value":{
                        "__type":"EntityReference:http://schemas.microsoft.com/xrm/2011/Contracts",
                        "Id":"97c90b02-4e38-ef11-a315-000d3a5a54dc",
                        "KeyAttributes":[

                        ],
                        "LogicalName":"systemuser",
                        "Name":null,
                        "RowVersion":null
                     }
                  }
               ],
               "EntityState":null,
               "FormattedValues":[

               ],
               "Id":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
               "KeyAttributes":[

               ],
               "LogicalName":"msdyn_agentstatus",
               "RelatedEntities":[

               ],
               "RowVersion":"5948260"
            }
         }
      ],
      "IsExecutingOffline":false,
      "IsInTransaction":false,
      "IsOfflinePlayback":false,
      "IsolationMode":1,
      "MessageName":"Update",
      "Mode":1,
      "OperationCreatedOn":"\/Date(1722582039000+0000)\/",
      "OperationId":"1a14c3ec-9c50-ef11-bfe3-00224802dbb1",
      "OrganizationId":"66aa66aa-bb77-cc88-dd99-00ee00ee00ee",
      "OrganizationName":"unq6042beb1a93aef118e4b00224802c",
      "OutputParameters":[

      ],
      "OwningExtension":{
         "Id":"8ff4bda5-9d4e-ef11-bfe3-00224802dbb1",
         "KeyAttributes":[

         ],
         "LogicalName":"sdkmessageprocessingstep",
         "Name":null,
         "RowVersion":null
      },
      "ParentContext":null,
      "PostEntityImages":[

      ],
      "PreEntityImages":[

      ],
      "PrimaryEntityId":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "PrimaryEntityName":"msdyn_agentstatus",
      "RequestId":"84d03007-6a8f-41da-aeae-7b6460bb7a04",
      "SecondaryEntityName":"none",
      "SharedVariables":[
         {
            "key":"IsAutoTransact",
            "value":true
         },
         {
            "key":"AcceptLang",
            "value":""
         }
      ],
      "Stage":30,
      "UserAzureActiveDirectoryObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
      "UserId":"d89254ff-9438-ef11-a315-000d3a5a54dc"
   },
   "PostEntityImages":[
      {
         "key":"AsynchronousStepPrimaryName",
         "value":{
            "Attributes":[
               {
                  "key":"msdyn_agentstatusid",
                  "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
               }
            ],
            "EntityState":null,
            "FormattedValues":[

            ],
            "Id":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
            "KeyAttributes":[

            ],
            "LogicalName":"msdyn_agentstatus",
            "RelatedEntities":[

            ],
            "RowVersion":null
         }
      }
   ],
   "PreEntityImages":[

   ],
   "PrimaryEntityId":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
   "PrimaryEntityName":"msdyn_agentstatus",
   "RequestId":"84d03007-6a8f-41da-aeae-7b6460bb7a04",
   "SecondaryEntityName":"none",
   "SharedVariables":[
      {
         "key":"IsAutoTransact",
         "value":true
      },
      {
         "key":"AcceptLang",
         "value":""
      }
   ],
   "Stage":40,
   "UserAzureActiveDirectoryObjectId":"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
   "UserId":"d89254ff-9438-ef11-a315-000d3a5a54dc"
}

Use APIs to get or modify presence status

You can use custom APIs to get or modify the service representative's presence status. Do the following steps to use these APIs:

  1. Generate tokens using in certificate based authentication using your application ID. Learn more in Use OAuth authentication with Microsoft Dataverse.
  2. Assign impersonation privileges to the application. Learn more in Impersonate another user using the Web API.
  3. Perform the required API calls as follows: