Agent Availability Events

This page documents webhook request payloads for Agent Availability Events. For an overview, see Webhook event types.

Detail object properties

For agent status events, the detail object contains the following properties:

• account_id
• agent_id
• version

Event types

The following sections contain example payloads and event object properties for agent status event types.

Event type	Payload and properties
zen:event-type:agent.state_changed	Agent Per Channel Status Changed
zen:event-type:agent.work_item_added	Agent Work Item Added
zen:event-type:agent.work_item_updated	Agent Work Item Updated
zen:event-type:agent.work_item_removed	Agent Work Item Removed
zen:event-type:agent.max_capacity_changed	Agent Maximum Capacity Changed
zen:event-type:agent.unified_state_changed	Agent Unified Status Changed
zen:event-type:agent.channel_created	Agent Channel Created
zen:event-type:agent.channel_deleted	Agent Channel Deleted
zen:event-type:agent.groups_updated	Agent Group Membership Updated

Agent Per Channel Status Changed

An agent's status for a specific channel changed. new_state indicates whether the agent's status is online, offline, or away on a particular channel.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "previous_state": "offline",
    "new_state": "online",
    "channel": "support"
  },
  "id": "01GX79ST1QX01C889XV42S2J5T",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.state_changed",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the agent's status changed
previous_state	string	The agent's previous status
new_state	string	The agent's current status
channel	string	The name of the channel for which the agent's status changed

Agent Work Item Added

A ticket, messaging conversation, or incoming call was assigned to an agent.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "work_item_id": "123",
    "channel": "support",
    "reason": "OFFERED"
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.work_item_added",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the work item was added
work_item_id	string	The id of the work item
channel	string	The name of the channel from which the work item originated
reason	string	The reason for adding the work item. Valid values: "UNKNOWN_ADD", "ASSIGNED", "OFFERED", "ACCEPTED"

Agent Work Item Updated

A ticket, messaging conversation, or incoming call previously assigned to an agent was updated.

{
  "account_id": 2,
  "detail": {
  "account_id": "2",
  "agent_id": "10011",
  "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "work_item_id": "123",
    "channel": "support",
    "previous_reason": "OFFERED",
    "reason": "ACCEPTED"
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.work_item_updated",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the work item was added
work_item_id	string	The id of the work item
channel	string	The name of the channel from which the work item originated
previous_reason	string	The previous reason for updating the work item, valid values: UNKNOWN_ADD, ASSIGNED, OFFERED, ACCEPTED.
reason	string	The reason for updating the work item, valid values: UNKNOWN_ADD, ASSIGNED, OFFERED, ACCEPTED.

Agent Work Item Removed

A ticket, messaging conversation, or incoming call previously assigned to an agent was removed.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "work_item_id": "123",
    "channel": "support",
	"reason": "REMOVED"
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.work_item_removed",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the work item was removed
work_item_id	string	The id of the work item
channel	string	The name of the channel from which the work item originated
reason	string	The reason for removing the work item, valid values: UNKNOWN_REMOVE, REMOVED.

Agent Maximum Capacity Changed

The maximum number of work items per channel that can be assigned to an agent changed.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "maxCapacity": {
        "talk": {"current": 10, "previous": null},
        "support": {"current": 15, "previous": null},
        "messaging":{"current": 5, "previous": null}
    }
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.max_capacity_changed",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the maximum capacity was changed
maxCapacity	object	Kay-value pairs specifying the maximum capacity for each channel. The key is the name of the channel and the value is an object containing the current and previous maximum capacities

Agent Unified Status Changed

An agent's unified or custom status changed.

{
  "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"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the agent's unified status was changed
previous_unified_state	object	The id, name and reason of the agent's previous unified status
new_unified_state	object	The id, name and reason of the agent's current unified status

Agent Channel Created

An agent gained access to a specific channel.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "channel": "support"
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.channel_created",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the channel was created
channel	string	The name of the channel

Agent Channel Deleted

An agent lost access to a specific channel. This could be the result of role, permission, or account changes.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "channel": "support"
  },
  "id": "01GX79ST1QX01C889XV42S2J5Z",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.channel_deleted",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the channel was deleted
channel	string	The name of the channel

Agent Group Membership Updated

An agent’s group memberships were updated.

{
  "account_id": 2,
  "detail": {
    "account_id": "2",
    "agent_id": "10011",
    "version": "3"
  },
  "event": {
    "updated_at": "2023-04-05T23:30:58.642630335Z",
    "previous_group_ids": ["123"],
    "new_group_ids": ["123", "456"]
  },
  "id": "01GX79ST1QX01C889XV42S2J5T",
  "subject": "zen:agent:10011",
  "time": "2023-05-10T23:31:58.642630335Z",
  "type": "zen:event-type:agent.groups_updated",
  "zendesk_event_version": "2022-11-06"
}

The event object contains the following properties.

Property	Data type	Description
updated_at	timestamp	The time the group memberships were updated
previous_group_ids	array	The ids of the groups that the agent previously belonged to
new_group_ids	array	The ids of the groups that the agent currently belongs to