Work Item Engagements

Zoom Contact Center work items are back-office tasks such as tickets, cases, or follow-ups. They are managed the same as other engagement types and can be created via API call to the start an engagement endpoint. Once created, work item engagements are routed to ZCC flows, assigned to queues, and delivered to agents or external systems in real time. They can be configured for dynamic use, allowing agents to create work items during or after engagements using agent-provided content and insight.

To create and use work item engagements in your ZCC environment, you'll need admin-access rights with your Contact Center account. Additionally, a valid access token is needed to authenticate your API calls and successfully create the engagement. You can generate your access token using your app credentials found on the marketplace.

Configure your app for API calls

To call the start an engagement endpoint, the following scope needs to be added to an admin-managed OAuth application or server to server (s2s) application: contact_center_engagement:write:admin

Generate your access token, using your Client ID and Client Secret, by sending a POST request to https://zoom.us/oauth/token. If using a general OAuth app, follow the user authorization flow to successfully generate your access token. Otherwise, if using an s2s application, use a basic authorization header to generate your token.

Create your API request

Work item engagements allow for complete customization within the request based on included values. At minimum, the following are necessary for creation:

  • channels.channel - the specified engagement channel (only supports work_item)
  • channels.channel_source - the channel source you want to start (only supports API)
  • flow.flow_entry_id - the entry ID for the desired destination flow
  • work_item_variables.work_item_name - the name of the work item being created

When sending your POST request to the engagement endpoint, use the following guidelines to mitigate conflicts:

  • If a key exists in both consumerInfo and variableList, the value from consumerInfo takes precedence.
  • If duplicate keys are provided within variableList, only the first occurrence is used.
  • If a key appears only once in variableList, the provided value is applied.

An example payload and success response is shown below:

'{
  "work_item_variables": {
    "work_item_id": "24fwet23525",
    "work_item_name": "Follow up with customer about refund status"
  },
  "flow": {
    "flow_entry_id": "4ad5A8qLTIunwdlpzSS4lg"
  },
  "language_code": "en-US",
  "channels": [
    {
      "channel": "work_item",
      "channel_source": "API"
    }
  ],
  "consumers": [
    {
      "consumer_display_name": "Jill Doe",
      "consumer_email": "JillDoe@example.com"
    }
  ]
}'

201 success return with engagement information:

{
    "work_item_variables": {
        "work_item_name": "Follow up with customer about refund status",
        "work_item_id": "24fwet23525"
    },
    "flows": [
        {
            "flow_entry_id": "4ad5A8qLTIunwdlpzSS4lg",
            "flow_id": "zeYjXoDOS_eV1QmTpj63PQ",
            "flow_name": "Demo",
            "flow_version": "5"
        }
    ],
    "session_id": "z7bc2vC5TPSliVBO4dhaoQ",
    "engagement_id": "vj9yy02ZTsyK22boIf2dww",
    "language_code": "en-US",
    "channels": [
        {
            "channel": "work_item",
            "channel_source": "API"
        }
    ],
    "start_time": "2025-09-01T00:00:00Z",
    "consumers": [
        {
            "consumer_display_name": "Jill Doe",
            "consumer_email": "JillDoe@example.com"
        }
    ]
}

Our returned object includes new data from the created work item engagement, including the start time, session ID, and additional flow details.