Description
Hello Genesys Cloud Developers,
In June 2024 we announced upcoming deprecation of Chat V2, including all related API endpoints, providing 1 year notice, to help you prepare for necessary migration steps. We recently refreshed this deprecation announcement to raise visibility within the Developer Community. As a result of this deprecation, the POST /api/v2/conversations/chats is formally tagged as deprecated and teardown is planned after June 11th 2025.
This API played an integral role in a lesser known feature called 3rd Party Object Routing(Genesys Cloud Developer Center) where it was possible to route a “container” that would represent a chat interaction in a 3rd party system. When the agent would accept the chat then it would be possible to “pop” this chat in the 3rd party system so that the agent could interact. It was also possible to utilize this chat interaction for other media-type purposes, such as to route a fax document, a case/ticket, a video interaction, etc.
With the extent that this 3rd party object routing feature is being used, we wanted to share a few options for you to adapt your current integration so that it will work after the deprecation of the ACD Chat v2 APIs.
Third-Party Email Routing
The first, and easiest, option is to move to calling POST /api/v2/conversations/emails instead of the chat endpoint, this entitlement is included in your same seat license. One could argue that the email endpoint is actually more capable since it has a superset of properties available and even allows for first sending the interaction to a flow for processing prior to sending it to a queue for routing. From an agent UI perspective there should be little to no difference besides the icon of the interaction displayed to the agent in their interaction roster. Perhaps the biggest effect of this change may be seen in reporting where the integration type will change from chat to email, so report filters may need to be changed accordingly.
Example of deprecated 3rd party chat request:
POST /api/v2/conversations/chats
{
"queueId": "264ce314-37b0-4f14-ba8c-521d827043b5",
"provider": "Crespino",
"attributes": {
"CRMChatUrl": https://the.chat.url
},
"customerName": "Some Customer Name"
}
Example of 3rd party email request:
POST /api/v2/conversations/email
{
"queueId": "264ce314-37b0-4f14-ba8c-521d827043b5",
"provider": "Crespino",
"attributes": {
"CRMChatUrl": https://the.chat.url
},
"fromName": "Some Customer Name",
"direction": "INBOUND"
}
Work Automation
The second, more involved but future-proofed, option would be to switch over to using the Genesys Cloud Work Automation feature (Genesys Cloud Developer Center). Work Automation allows for the routing of “workitems” that can literally represent anything that you need to route to an agent. Creating a Workitem interaction is as easy as calling POST /api/v2/taskmanagement/workitems and the properties there should look very familiar. Workitems can have schemes associated with them to allow for custom properties for different workitem types. The agent UI experience is better, as is reporting. Note that there is an add-on cost for using Work Automation, so please discuss this with your Genesys account team.
Example of workitem creation:
POST /api/v2/taskmanagement/workitems
{
"name": "Some Customer Name",
"typeId": "367f3383-9e81-4a9f-ad18-1d644acfee2a",
"queueId": "264ce314-37b0-4f14-ba8c-521d827043b5",
"description": "Represents a 3rd party object being routed",
"customFields": {
"description_text": "my description",
"notes_longtext": "my notes",
"linkurl_url": https://the.chat.url
}
}
We understand the hardship that this change is likely to cause. We strive to do our best to make non-breaking changes to our API, but sometimes feature deprecations must occur for us to make advances in other product areas. Should you have any questions as you attempt to transition your code to one of the two options above, please feel free to ask questions on the Genesys Cloud Developer Forum (Genesys Cloud Developer Forum ) and we’ll be happy to help answer those for you.
Change Category
Infrastructure
Informational
API
Change Context
See description
Change Impact
See description
Date of Change
Deprecation annotation change takes effect immediately.
Removal subject to no usage : After 11 June, 2025
Impacted APIs
POST /api/v2/conversations/chats
References
[WC-1127]