[BREAKING] Changes to Talk Agent Availabilities API Endpoint for Omnichannel Routing customers

Omnichannel Routing (currently in EAP) enables you to direct tickets generated from Zendesk Support email, webform, API, and messaging conversations to agents based on the ticket's priority and the agent's status and capacity. The upcoming beta release of Omnichannel Routing (more information will be available soon) also includes the agent statuses EAP which enables agents to set a single unified status across multiple channels in the Agent Workspace where previously you could separately set an agent status for Talk channel.

If you are opted-in to the Omnichannel Routing EAP or enable Omnichannel Routing Beta or GA when released, and are using the Update Talk agent availability API, it will no longer function if the agent_state property of availability object is being updated. Any integrations or apps that use Talk agent availability API end-point might also be impacted.

This article documents the impact to the Talk agent availability API endpoint with the release.

What are the changes to the Talk Agent Availability APIs?

Below are the changes to the Show and Update Talk Agent Availability APIs:

• Changes to the ‘Show Availability’ endpoint
  •  GET /api/v2/channels/voice/availabilities/{agent_id} 
  • This API will return the current Talk status as inferred from the unified agent status. For example, if a custom status is set to  "In a meeting", because of which Talk channel Status becomes Away, Messaging channel status also becomes Away and Email status becomes Online. Show Talk Agent Availabilities endpoint will return "Away" if queried.
    • Response: 
      • {"availability":{"via":"client","agent_state":"away","call_status":null}}
    • The request and response continue to work as before without change. 
• Changes to the ‘Update Availability’ endpoint
  • PUT /api/v2/channels/voice/availabilities/{agent_id} 
  • The PUT endpoint will return 400 bad_request, if the agent_state property of availability object is being updated through the API
    • Curl request example: curl https://{subdomain}.zendesk.com/api/v2/channels/voice/availabilities/{agent_id}.json -H "Content-Type: application/json" -d '{"availability": {"via": "client", "agent_state":  "online"}}' -v -u {email}:{pasword}! -X PUT
    • Response: 400 Bad Request {"error":"agent_state is not a valid parameter when OcR is enabled"}
  • Update to the “via” property of an availability object through the API continues to work as before without change.
    • Curl request example: curl https://subdomain.zendesk.com/api/v2/channels/voice/availabilities/{agend_id}.json -H "Content-Type: application/json" -d '{"availability": {"via": "client"}}' -v -u {email}:{password} -X PUT
    • Response: 200 OK {"availability":{"via":"client","agent_state":"offline","call_status":null}

Who is getting impacted?

This change impacts customers who use these APIs and opt-in to Omnichannel Routing either as part of Beta or GA.

Additionally, for our partners who build applications and integrations on top of these APIs, your customers who onboard onto the release might be impacted depending on your use of the API.

What are the key dates for the changes?

We are planning to launch the Omnichannel Routing beta by the end of Aug 2022 and GA by Mid October 2022.

What are my options to mitigate the change?

At the moment we are not able to offer any substitute for the current Update Talk Agent availability API.

If your workflow is impacted by the change we recommend you to not enable Omnichannel Routing in its first version. We plan to release an API to change agent statuses in a unified way across channels in later versions.

What are the future plans for changing agent statuses via APIs?

We are planning to release the new public APIs to view and update unified agent statuses across Zendesk channels as part of our next nine months roadmap. More detailed release plans and timelines will be announced later.