Great thread, thanks Brian for the detailed clarifications. One practical implication worth flagging for anyone building on top of this, since it follows directly from the "agentCount = touched agents, not total" behavior:
So the safe pattern really is: treat every event purely as a "something changed, go refresh" trigger, and always call GET .../schedules/{scheduleId}?expand=managementUnits.agents for the actual current state when you need it, rather than accumulating state incrementally from the notification payloads. Worth calling that out explicitly since it's the kind of thing that works fine in testing and then quietly produces wrong counts in production once real editing patterns kick in.
Original Message:
Sent: 09-04-2026 10:05
From: Brian Trezise
Subject: Questions about WFM Schedule API
Thanks for the follow-up and the detailed test case.
On agentCount: no, this isn't specific to publish, it's the general behavior of that field. Publish isn't really a separate operation, either, it's just a regular schedule save where the published flag happens to be set, going through the same update path as any other save. So every event on the schedules topic, create, copy, update, delete, publish, reports agentCount the same way, the number of agents whose shifts were actually touched by that specific save, not the schedule's total agent count. A dedicated event carrying the full agent count on publish is a reasonable idea, but that would be a new capability rather than a fix.
On your test case, both behaviors you're seeing are expected, and they come from the same mechanism as the agentCount point above. Schedule A's event shows published: false with no managementUnits because publishing B only flips A's published flag as a side effect, it doesn't touch any of A's individual agent shifts. Since nothing was touched, there's nothing to report, so the managementUnits list ends up empty. Schedule B's event only includes the one management unit with agents for the same underlying reason, a management unit with zero agents has nothing that could have been touched, so it's never included in that array, independent of publish or agentCount specifically.
On the agentschedules/query complexity: I understand the frustration with three different response shapes depending on timing and payload size. There genuinely isn't a REST endpoint to check status or results by operationId after the fact though, that gap is real. This pattern predates the "jobs" pattern we've used more recently for other async operations, which does support that kind of lookup, but retrofitting this existing route would need real customer demand behind it to justify the change.
If either of those, a dedicated publish event or an operationId lookup here, would help you, I'd encourage filing them on the Ideas portal (https://genesyscloud.ideas.aha.io/ideas). That's genuinely how we gauge what customers actually want when we're weighing where to put engineering time, so it carries real weight, not just a formality.
------------------------------
Brian Trezise
Genesys - Employees - Lead Software Engineer
------------------------------
Original Message:
Sent: 09-04-2026 07:20
From: Stéphane Labrune
Subject: Questions about WFM Schedule API
Hi,
Thank you for the various responses to my questions.
Here are my comments:
I do not really see in the documentation how it is understood that there are no notifications on v2.workforcemanagement.businessunits.{businessUnitId}.schedules during generation, but if that is indeed the expected behavior, that's fine with me.
Regarding agentCount = 0, is this the only case where it corresponds to a schedule being published? If not, having a dedicated event for schedule publication would be helpful.
I would also like some feedback on this test to validate the functioning of the same event:
Two schedules covering the same dates (A: published, B: unpublished).
I publish schedule B:
- Schedule A switches to unpublished, B switches to published.
- An event on v2.workforcemanagement.businessunits.{businessUnitId}.schedules concerning A:
--> published: false and no managementUnits object (thus no agentCount), is this normal? - An event on v2.workforcemanagement.businessunits.{businessUnitId}.schedules concerning B:
--> published: true, managementUnits present (with agentCount: 0).
However, I notice there are two managementUnits in my businessUnit, but one does not have any agents, so the event's array contains only one object. Is this expected?
Regarding the agentschedules/query API, I understand how it works.
However, we find that its usage is too complex.
While we understand the reason for the asynchronous approach, not being able to force asynchronous behavior in production seems problematic.
This would allow for a unified handling of the API's behavior, whereas currently, there are three modes: synchronous with data, synchronous with download URL, and asynchronous (via EventBridge in our solution).
We haven't found a REST API that, starting from an operationId, allows us to retrieve data (or at least the status if it's 'processing').
Perhaps we are mistaken, or this is a missing feature in the API, there are cases where asynchronous operations are not possible (we can use EventBridge, but not WebSocket for example).
Best regards.
------------------------------
Stéphane
NA
------------------------------
Original Message:
Sent: 09-02-2026 12:20
From: Brian Trezise
Subject: Questions about WFM Schedule API
Following up on the three points from this thread:
1. No notification when a schedule is created (unpublished)
This depends on how the schedule was created:
- If it was created as a blank/new schedule directly, you will get a notification on v2.workforcemanagement.businessunits.{businessUnitId}.schedules, whether or not it's published at that point.
- If it was created via schedule generation (the scheduler run), no notification is sent on that schedules topic for the creation itself. Instead, you'll get notifications on v2.workforcemanagement.businessunits.{businessUnitId}.scheduling.runs as the run progresses and completes; that notification includes a reference to the resulting schedule's ID once the run finishes, but not the full schedule payload the schedules topic carries. So if generation was the method used here, seeing nothing on the schedules topic is expected behavior, not a bug; you'd want to be subscribed to the scheduling runs topic instead.
2. agentCount showing 0 on publish
This is working as intended on our side, not a bug in the behavior itself. `agentCount` reflects the number of agents whose shifts were actually changed by that specific request, not the total number of agents on the schedule. If you publish a schedule in a request that itself doesn't add, edit, or delete any shifts (e.g. the shifts were already saved earlier and this call just flips the schedule to published), zero shifts were changed by that request, so `agentCount` of 0 is correct under that definition, even though the management unit clearly has agents with shifts once it's published.
That said, I found that our published documentation for this field doesn't describe it that way; it currently reads as if it reflects the total agent count on the schedule, which is a reasonable thing to have expected given the doc. The update-schedule guide walks through this update/publish flow and links out to the API reference where that response schema, and this field's description, actually live. I've created an internal ticket to look into correcting the documentation to accurately describe the current behavior. We can't change the field's actual behavior to match that wording, since it's already a consumed field and redefining it now would be a breaking change for existing callers, but the doc should match reality, so thanks for flagging it.
3. Polling the async agent schedules query
Each POST to that query endpoint starts a brand new, independent asynchronous operation with its own operation ID; there's no way to pass in a prior operation ID to resume or check on it, and there's no separate endpoint to look up the status of a past operation ID by itself. So issuing another POST is never "polling"; it's always a new query. This matches the guidance already given in this thread: subscribe to the notification topic first, submit the query once, and correlate the result using the operation ID from the response.
There isn't a dedicated guide for this specific query, but it follows the same subscribe-then-query async flow as the search published agent schedule guide. That guide's linked reference is for the search route though, not this one; the actual reference for this query route is here.
This endpoint also doesn't always come back asynchronously. If the query completes quickly enough, the response comes back synchronously in that same call with the result included, and no async notification is sent for it at all. It only falls back to the async/notification pattern if the query is still running after a short wait in order to ensure the call doesn't time out. So rather than always waiting on a notification, check the status in the immediate response first; for smaller queries, the answer is often already there.
As for why this is set up this way: this route predates our current event-driven notification framework, so it wasn't originally designed to support that request/resume pattern; the async/notification behavior was layered on afterward rather than being part of the route's original design, which is why it doesn't support resuming or checking on a prior operation the way a route built for that pattern from the start would. If that capability would be valuable to you, I'd encourage submitting an idea on the Ideas portal so we can gauge demand for expanding this.
On the 500 error / that specific topic
I can't say what caused the 500 from what's available here, but that particular notification topic is completely unused; the back-end that used to drive it no longer exists. I've created another internal ticket to look at cleaning this up, so I wouldn't recommend building against it going forward.
------------------------------
Brian Trezise
Genesys - Employees - Lead Software Engineer
------------------------------
Original Message:
Sent: 08-31-2026 10:38
From: Stéphane Labrune
Subject: Questions about WFM Schedule API
Thank you for your response.
Concerning agentschedules/query API part I agree :
Polling seems unnecessary because the operationId will indeed be different each time.
Relying on an event (via WebSocket or EventBridge) to retrieve the schedules for a few agents appears to be overly complex for little benefit, especially considering that this is not the case for a schedule_id.
Regarding the events related to v2.workforcemanagement.businessunits.{id}.schedules, I also agree.
The documentation is very limited, making it difficult to understand the different scenarios.
I tested the topic v2.workforcemanagement.managementunits.{id}.schedules, but it returned a 500 error. It seemed interesting because it includes a downloadUrl.
I hope Genesys will provide more comprehensive responses and documentation on this.
------------------------------
Stéphane
NA
------------------------------
Original Message:
Sent: 08-31-2026 10:01
From: Fernando Sotto dos Santos
Subject: Questions about WFM Schedule API
Hi Stéphane,
I think there are two slightly different mechanisms involved here, so I would be careful about treating them as the same workflow.
Regarding v2.workforcemanagement.businessunits.{id}.schedules, the notification contract does expose status, operationId, eventType and a result that may contain the management units, agents and agentCount.
However, I could not find anything in the official documentation that defines a strict lifecycle matrix such as:
Create - event
Publish - event with complete agent snapshot
Update - event
Delete - event
In fact, the properties in the notification model are optional, so I would be cautious about interpreting agentCount = 0 on the initial publish event as meaning that the Management Unit actually has zero scheduled agents.
It could represent the state of the payload at that particular stage of the operation rather than a guaranteed full snapshot of the schedule. I would not call it a bug without further confirmation from Genesys, but I also would not use that value alone as the authoritative source for the schedule.
For a more defensive integration pattern, I would use the notification primarily as a change signal, and then retrieve the current schedule metadata using:
GET /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekId}/schedules/{scheduleId}?expand=managementUnits.agents
The documentation specifically describes this endpoint as returning the schedule metadata, including which Management Units and agents are part of the schedule.
This would also make an interesting validation test: immediately after receiving the Publish notification with agentCount = 0, call the metadata endpoint. If the API metadata already returns the agents correctly while the notification still contains zero, then we have much stronger evidence that the notification payload has different semantics - or potentially an issue worth raising with Genesys.
The fact that no notification is received when an unpublished schedule is created is similar: I could not find an official statement guaranteeing that this particular topic fires for every schedule lifecycle operation, so I would hesitate to confirm that behavior as either expected or incorrect based solely on the current documentation.
Regarding:
POST /api/v2/workforcemanagement/businessunits/{businessUnitId}/weeks/{weekId}/schedules/{scheduleId}/agentschedules/query
this is a different matter.
The endpoint is designed to support both direct and asynchronous results. The documentation explicitly provides forceAsync and forceDownloadService, although those parameters are intended for testing/development rather than for controlling normal production behavior.
So I would not repeatedly POST the same query as a polling mechanism when the returned status is Processing. A new POST represents another query operation rather than polling the existing operationId.
There is a separate WFM notification topic for the asynchronous query result:
v2.workforcemanagement.users.{id}.schedules.query
Therefore, my understanding of the intended pattern would be:
subscribe to query notification
-POST agentschedules/query once
- if Complete, consume the result
- if Processing, wait for the corresponding completion notification and correlate it using operationId
- if the completed response contains downloadUrl, retrieve the result from that URL.
Also, since you are currently consuming the Business Unit schedule topic through EventBridge, I would make sure the user schedules query topic is subscribed as well. The Business Unit topic is telling you that something changed in the schedule; it is not the same topic used to deliver the result of the asynchronous agentschedules/query.
One additional point confirmed previously by Genesys is that the size of the result determines whether the schedule can be returned inline or via the download service. Setting forceAsync=false or forceDownloadService=false does not guarantee synchronous/inline behavior.
So, in summary, I would treat the first issue (agentCount = 0) as something that still needs clarification from Genesys regarding the exact notification semantics, while the asynchronous query/download behavior appears to be part of the documented API design.
Hope this helps - and I would also be interested in a Genesys confirmation specifically around what agentCount is expected to represent on the initial Publish event.
------------------------------
Fernando Sotto dos Santos
Consultor de Atendimento Senior Grupo Casas Bahia
------------------------------