Configure automatic closure of conversations using web API

Omnichannel for Customer Service offers a suite of capabilities that extend the power of Dynamics 365 Customer Service Enterprise to enable organizations to instantly connect and engage with their customers across digital messaging channels. An additional license is required to access Omnichannel for Customer Service. For more information, see the Dynamics 365 Customer Service pricing overview and Dynamics 365 Customer Service pricing plan pages.

This article demonstrates how you can configure the auto-close duration of a conversation using the Web API.

Important

Duration-based automatic closure of conversations isn't supported for records that're configured for unified routing. When you delete a routed record, the associated queue item is deleted. The live work item or conversation will also be deleted as part of the clean-up process.

Use the following GET request to fetch all the configuration records that have been defined out of the box.

Request

GET [Organization URI]/api/data/v9.1/msdyn_occhannelstateconfigurations
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Response

{ 
   "@odata.context":"[Organization URI]/api/data/v9.1/$metadata#msdyn_occhannelstateconfigurations",
   "value":[ 
      { 
         "@odata.etag":"W/\"1379367\"",
         "_organizationid_value":"758f70a9-7aba-4764-bdda-fcc0023a702f",
         "msdyn_name":"Live Chat - Open",
         "statecode":0,
         "statuscode":1,
         "_msdyn_occhannelconfigurationid_value":"836717fd-5578-e911-8196-000d3af7d71e",
         "msdyn_autocloseliveworkitemafter":20,
         "modifiedon":"2019-10-01T13:41:51Z",
         "_modifiedby_value":"d6e088ce-8866-4b3d-8ea2-150ad72e2b79",
         "msdyn_ocliveworkitemstate":0,
         "msdyn_showconfirmationonsessionclose":false,
         "versionnumber":1379367,
         "msdyn_occhannelstateconfigurationid":"6283ab63-5778-e911-8196-000d3af7d71e",
         "createdon":"2019-10-01T13:41:51Z",
         "_createdby_value":"d6e088ce-8866-4b3d-8ea2-150ad72e2b79",
         "_modifiedonbehalfby_value":null,
         "importsequencenumber":null,
         "overriddencreatedon":null,
         "_createdonbehalfby_value":null,
         "utcconversiontimezonecode":null,
         "timezoneruleversionnumber":null
      },
      { 
         "@odata.etag":"W/\"1379368\"",
         "_organizationid_value":"758f70a9-7aba-4764-bdda-fcc0023a702f",
         "msdyn_name":"Live Chat - Active",
         "statecode":0,
         "statuscode":1,
         "_msdyn_occhannelconfigurationid_value":"836717fd-5578-e911-8196-000d3af7d71e",
         "msdyn_autocloseliveworkitemafter":null,
         "modifiedon":"2019-10-01T13:41:51Z",
         "_modifiedby_value":"d6e088ce-8866-4b3d-8ea2-150ad72e2b79",
         "msdyn_ocliveworkitemstate":1,
         "msdyn_showconfirmationonsessionclose":true,
         "versionnumber":1379368,
         "msdyn_occhannelstateconfigurationid":"e2737c9a-5778-e911-8196-000d3af7d71e",
         "createdon":"2019-10-01T13:41:51Z",
         "_createdby_value":"d6e088ce-8866-4b3d-8ea2-150ad72e2b79",
         "_modifiedonbehalfby_value":null,
         "importsequencenumber":null,
         "overriddencreatedon":null,
         "_createdonbehalfby_value":null,
         "utcconversiontimezonecode":null,
         "timezoneruleversionnumber":null
      },
   ]
}

The msdyn_name attribute in the msdyn_occhannelstateconfiguration entity mentions the channel and state of the conversation. For more information about conversation states, see Understand conversation states in Omnichannel for Customer Service.

You can make a GET request to the msdyn_occhannelconfiguration entity to fetch all the existing channel records. For each of these channels, you can see its state when you query the msdyn_occhannelstateconfiguration entity.

Make a PATCH request to the msdyn_occhannelstateconfiguration entity record and update the value of the msdyn_autocloseliveworkitemafter attribute.

PATCH [Organization URI]/api/data/v9.1/msdyn_occhannelstateconfigurations(6283ab63-5778-e911-8196-000d3af7d71e)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

{
    "msdyn_autocloseliveworkitemafter":5
}

Here's a sample code for updating existing records in the msdyn_occhannelstateconfigurations entity:

var data =
    {
        "msdyn_autocloseliveworkitemafter": 2
    }
// update the record
Xrm.WebApi.updateRecord("msdyn_occhannelstateconfiguration", "6283ab63-5778-e911-8196-000d3af7d71e", data).then(
    function success(result) {
        console.log("Auto close time updated");
    },
    function (error) {
        console.log(error.message);
    }
);

Note

The value for the msdyn_autocloseliveworkitemafter attribute is in minutes. If you want to provide a value that is in days, you'll have to convert it into minutes. For example, 1 day will be 24 x 60 = 1,440 minutes.

The conversation closes automatically if the value of the msdyn_autocloseliveworkitemafter attribute is greater than the value of the createdon attribute.

If the conversation is in the wrap-up state—that is, the agent has resolved the issue and can now perform some post-conversation steps to close the conversation—then the conversation is closed if the value of the msdyn_autocloseliveworkitemafter attribute is greater than the value of the wrapupinitiatedon attribute.

Important

The decision to close a conversation based on the values of the msdyn_autocloseliveworkitemafter and createdon attributes is made when a scheduled job runs, and not when the PATCH Web API request is run.

Configure automatic closure of Wrap-up state for live chat

The default time for automatically closing a live chat that's in Wrap-up state is 15 minutes. The value is defined in the msdyn_autocloseliveworkitemafter attribute and can be programmatically changed to suit your business needs.

The value defined for the Block capacity for wrap-up field in the workstream overrides the value specified in the msdyn_autocloseliveworkitemafter attribute, if it is more than the value for the msdyn_autocloseliveworkitemafter attribute. For example, if you have set the value for blocking agent's capacity as 15 minutes and the msdyn_autocloseliveworkitemafter attribute as 10 minutes, a conversation in Wrap-up state will occupy capacity for 15 minutes and will be eligible for automatic closure only after 15 minutes.

Next steps

Update an entity using Web API

See also

Automatic closure of conversations