Agent Status API – Playlist

To automatically receive tickets through round robin, the agent must be online in Playlist. All agents can update their own status, and admins/managers can update the status of other agents through the app. This API lets you update agent statuses from third-party tools and custom integrations.

The most common use case is to make agents available based on pre-defined work hours. For example, you can use a tool like Zapier to create a scheduled job that automatically uses the API to set agents online at 8 am, Monday through Friday.

Authentication

For instructions on authenticating, please see Playlist API authentication and security.

Endpoints

All endpoints start with https://api.myplaylist.io. For example, the full endpoint for the /zendesk/user_statuses/current path would be:

https://api.myplaylist.io/zendesk/user_statuses/current

List current user statuses
Show a user's current status
Create many user statuses

List current user statuses

GET /zendesk/user_statuses/current

Example response

{
   "user_statuses": 
   [      
      {
         "user_id": 361576231073,
         "status": "away",
         "updated_at": "2020-07-20T09:23:31.018Z",
         "updated_by": 361576231073
      },      
      {
         "user_id": 364058107113,
         "status": "online",
         "updated_at": "2020-07-20T09:23:31.018Z",
         "updated_by": 361576231073
      }
   ]
}

Show a user's current status

GET /zendesk/users/{user_id}/statuses/current

Get the current status for a specific agent.

Example response

{
   "user_status": 
   {
      "user_id": 364376160694,
      "status": "online",
      "updated_at": "2020-07-20T09:23:31.018Z",
      "updated_by": 361576231073
   }
}

Create many user statuses

POST /zendesk/user_statuses/create_many

Create user status records to set an agent's status. Use this endpoint to bulk create user statuses.

Parameters

Name	Type	Mandatory	Comment
user_statuses	array of user status objects	yes	Example [{"user_id": 12345, "status":"online" }, {"user_id": 12346, "status":"away"}] user_id The agent's Zendesk user ID. status Valid statuses: online, away, invisible. Limit of 1000 user statuses per request.
notify_app	boolean	no	Refreshes the agent's status in Playlist and displays a notification to the agent. Defaults to true.

Example request body

{
   "user_statuses": 
   [      
      {
         "user_id": 361576231073,
         "status": "online"
      },      
      {
         "user_id": 364058107113,
         "status": "online"
      }
   ]
}

If a user is already in the specified status, it will be ignored.
If duplicate user IDs are in the request, the first occurrence will be used and all other duplicates will be ignored.
Only successfully created user statuses are returned in the response.

Example response

{
   "user_statuses": 
   [      
      {
         "user_id": 361576231073,
         "status": "online"
      },      
      {
         "user_id": 364058107113,
         "status": "online"
      }
   ]
}