Syncing Zendesk unified agent statuses to Playlist Routing

If your team uses Zendesk unified agent statuses, you can keep Playlist Routing in sync automatically. When an agent changes their status in Zendesk, an action flow sends the change to Playlist Routing through the Agent Status API.

Before you begin

• You need to be a Zendesk admin.
• Your account must use omnichannel routing. Zendesk only sends unified status events for accounts with omnichannel routing turned on.
• You need your Playlist Routing API key.

How it works

1. An agent changes their unified status in Zendesk.
2. A Zendesk webhook sends the Agent unified status changed event to your action flow.
3. A custom code step maps the Zendesk status ID to a Playlist Routing status key.
4. A custom action calls the Playlist Routing Agent Status API to update the agent's status.

The sync is one-way: Zendesk is the source of truth. We recommend disabling the agent status picker in Playlist Routing by role so agents only change their status in Zendesk.

Step 1: Create a connection

The connection stores your Playlist Routing API key so the action flow can call our API.

1. In Admin Center, go to Apps and integrations > Connections > Connections, then click Add connection.
2. Select Custom connection, then click Next.

3. Enter the following:
   • Connection name: playlist_routing_api
   • Authentication type: API Key
   • Header name: X-API-Key

4. In Value, paste your Playlist Routing API key.
5. In Allowed domain, enter api.myplaylist.io.
6. Click Save.

Step 2: Create a custom action

The custom action sends a request to Playlist's Agent Status API to update an agent's status.

1. Go to Apps and integrations > Actions > Custom actions, then click Create custom action.
2. Enter the following:
   • Name: Update Playlist Routing agent status
   • Description: Sets an agent's status in Playlist Routing using Playlist's Agent Status API. Expects a user ID and a status key.
3. Under Inputs, add two inputs:
   • user_id (Number): Zendesk user ID
   • status (Text): Key of the status to set: online, away, invisible, or the key of a custom status

4. Under API configuration, enter the following:
   • Request method: POST
   • Endpoint URL: https://api.myplaylist.io/zendesk/user_statuses/create_many
   • Authentication: playlist_routing_api

5. In Body, enter the request below. Use the {+} button to insert the user_id and status inputs where shown. Do not remove the quotes wrapped around {{status}}.

   {
     "user_statuses": [
       {
         "user_id": {{user_id}},
         "status": "{{status}}"
       }
     ]
   }

6. Click Save.

Step 3: Create an action flow with a custom trigger

1. Go to Apps and integrations > Actions > Action flows and create a new action flow.
2. Click Add trigger, then under Custom triggers, click Create trigger.

3. For Name, enter Agent unified status changed.
4. For Sample payload, paste the below example from Zendesk's documentation for the Agent Unified Status Changed event, then click Next.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "previous_unified_state": {
      "id": "1", 
      "name": "offline",
      "reason": "UNKNOWN"
    },
    "new_unified_state": {
      "id": "2", 
      "name": "online",
	  "reason": "AGENT_LOGOUT"
    }
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.unified_state_changed",
  "zendesk_event_version": "2022-11-06"
}

5. Click Add next to these two fields:
   • agent_id under detail
   • id under event > new_unified_state
6. Click Next.

7. Zendesk creates the trigger and shows its webhook URL. You'll copy it in Step 6, so click Done for now.

Step 4: Add a custom code step

This step maps each Zendesk unified status ID to a Playlist Routing status key.

1. Below the trigger, add a Custom code step.
2. Under Inputs, click Add input, select the trigger's agent_id variable, and name it eventAgentId. Click Save.

3. Add a second input, select the trigger's id variable, and name it eventStatusId. Click Save.

4. Under Outputs, add two outputs:
   • user_id (Number)
   • status (Text)

5. In Code, paste the following. Replace the custom status IDs and keys with the ones from your account (see Status mapping below).
    

   // Maps Zendesk unified status IDs to Playlist agent status keys.
   module.exports = (inputs) => {
     const PLAYLIST_STATUS_BY_UNIFIED_STATUS_ID = {
       // Zendesk default statuses
       "2": "invisible",
       "3": "online",
       "4": "away",
   
       // Custom statuses: replace with your account's IDs and status keys,
       // or remove these lines if you don't use custom statuses.
       "746640": "lunch",
       "746641": "on_holidays",
       "746757": "meeting",
     };
   
     // Unmapped IDs fall back to "unmapped", which the API rejects with a 422.
     // That fails the flow run without retrying or updating the agent.
     const status = PLAYLIST_STATUS_BY_UNIFIED_STATUS_ID[inputs.eventStatusId] || "unmapped";
   
     return {
       status,
       user_id: Number(inputs.eventAgentId),
     };
   };

Step 5: Add the custom action

1. Below the custom code step, add a step and search for Update Playlist Routing Agent Status. Select it under Custom actions.

2. For status, click Add variable and select status from the 2 </> Custom code menu.

3. For user_id, select user_id from the 2 </> Custom code menu.
4. For Error handling, select Retry on error and Stop flow.
5. Name the action flow Sync Unified Status To Playlist Routing, then click Save and Activate.

Step 6: Copy the trigger's webhook URL

1. In the action flow, click the trigger step.
2. Click the options menu (three dots) in the trigger panel, then click Copy webhook URL. You will paste the URL in the next step.

Step 7: Create a webhook for unified status changes

1. Go to Apps and integrations > Webhooks > Webhooks, then click Create webhook.
2. Select the Zendesk events tile, then select the Agent unified status changed event. Click Next.

3. Enter a name for the webhook, such as Agent Unified Status Changed Webhook
4. In Endpoint URL, paste the webhook URL you copied in Step 6.
5. Leave Authentication set to None, since the webhook URL already contains a secret.
6. Click Create webhook.

To test the setup, change your own status in Zendesk. Then, confirm your status in Playlist Routing.

Status mapping

Zendesk's default status IDs are the same in every account:

Custom statuses: Custom status IDs are unique to your account. To find one, switch to that status once, then open the action flow's Runs tab and check the id value from the trigger. Add the ID to the mapping with the matching status key from Playlist Routing.

Transfers only: Playlist Routing doesn't have a Transfers only status. You can hide it from agents in Zendesk or map ID 5 to away or one of your existing Playlist Routing statuses.

Unmapped statuses: If a status isn't in the mapping, the API rejects the request and the agent's status in Playlist Routing doesn't change. The run shows as failed in the action flow's Runs tab, which is a good signal that a new status needs to be added to the mapping.

Out of office: Status changes made through this sync will trigger Routing's Out of Office feature if it's enabled.