Integrating Genesys Cloud CX and Zendesk with data actions

Picture a service desk at 08:55. A customer rings about a fault they reported yesterday. Everything about them is in Zendesk: their user record, their organisation, the open ticket and the comments added overnight. The agents who answer the phone, however, work in the Genesys Cloud CX agent workspace, and the IVR that greets the caller is an Architect flow. Without an integration, the caller repeats who they are, the agent searches by hand, and the first minute of the call is spent finding a ticket that already exists.

The question our client asked was precise: how do we make Zendesk information available to callers and agents inside Genesys Cloud, quickly and reliably enough to drive the IVR itself? Our answer treats Zendesk as the system of record and Genesys Cloud as the system of engagement, joined by data actions. A caller can hear the status of their open tickets, raise a new ticket without waiting for an agent and, if they still need help, reach an agent whose screen already shows the caller and the ticket they have just created. Getting that last step right turned out to depend on one choice of API, which we explain below.

Good integrations start in the data model, not in the flow. Zendesk's user record already holds the name, phone number and email address, but not everything the contact centre needs to steer a call. We added custom user fields for the account number, the current balance, the date of last contact, the preferred language (so the IVR speaks in the right language and persona), the customer's lifetime value to the business and the customer segment, such as Gold, Silver or Bronze. Each field gets the narrowest sensible type: Zendesk offers types including text, date, decimal, integer and drop-down, and a drop-down is the right choice wherever the flow will branch on the value.

Each custom field has a key, made only of letters, numbers and underscores, and the API returns the values under user_fields on the user, keyed by that field key. Data action request templates and translation maps must use the key, never the display name, so we record each field's display name, key, type and the flow decision that depends on it in the interface contract. A later rename in Zendesk is then caught as a breaking change in review rather than discovered as a silent lookup failure in production. Just as important is what we leave out: no verification secret is held in a Zendesk field that the IVR or an agent can read.

In Genesys Cloud, the Zendesk data actions integration holds the connection. Its credentials are the email address of a verified Zendesk user, an API token generated in Zendesk, and the base service URL of the Zendesk account, in the form https://{subdomain}.zendesk.com. Because the credentials live on the integration, no individual action carries a secret, and rotating a token is a change in one place. When the integration is activated, Genesys Cloud creates static actions automatically: get a user by phone number, email address, user ID or user name; get an organisation by ID or name; get a ticket by ticket ID; and get the most recent ticket by user ID or email address.

Static actions are useful on their own, and they make good templates, but a real journey needs more. We copied and extended them, and wrote new custom actions: get the open tickets for a user, read a ticket's comments, create a ticket from the IVR and add a comment to an existing one. Genesys describes custom actions as able to retrieve, update or create any data through Zendesk's REST API. Every custom action goes through the same four steps: define the input and output contracts, configure the request and the response, test it against real data, and publish it so that Architect flows and scripts can use it.

A data action's contracts are its promise to the flow. The input contract for our get-most-recent-ticket action has one required property: the Zendesk user ID, supplied by the earlier lookup. Genesys limits input contract properties to simple types, string, integer, number, Boolean and null, with no nested objects. The output contract describes what comes back: a count of tickets and a tickets array whose items carry the ticket ID, subject, status, created and updated dates, assignee and group, and the other fields the flow or the script will use. We return only what the journey needs; a smaller contract is easier to test and harder to break.

A correctly shaped response schema is what keeps the action from failing at runtime, and arrays deserve particular care. Genesys notes that the output contract does not support nested arrays, and that a resolved response must conform to the action's success schema or the action errors. Before we write a contract, we call the Zendesk endpoint from an API client such as Postman and read a real response, including the awkward cases: a user with no tickets, a ticket with an empty field, and a user with more tickets than one page returns.

Every contract needs a request URL template that asks Zendesk the right question. There are two natural ways to ask for a caller's recent tickets. The Search API template queries for tickets of type ticket, with a status below solved and the requester set to the input ID, sorted by last update. The Users API template asks only for the tickets requested by one user, with the user ID in the path, sorted by creation date with the newest first. Both return the same ticket objects. We URL-encode every input with esc.url(), as Genesys requires for path and query parameters, even when the input is a numeric ID.

The difference that matters is freshness. The Search API looks across every ticket in the account through a search index, and Zendesk documents that new tickets can take up to a few minutes to be indexed. In our testing, a newly created ticket could take two minutes or more to appear in search results, while the user-scoped request returned it straight away. If a caller raises a ticket in a bot flow and is then routed to an agent who must see that ticket in the screen pop, a lag of minutes breaks the journey. That use case needs the Users API route.

Zendesk's own documentation adds a refinement we now build in. For the requested-tickets endpoint, it notes that requests which include both active and archived tickets can see a short delay before new tickets appear, with most available within 30 seconds and the vast majority within 90. The endpoint accepts an exclude_archived parameter, and because the IVR only ever needs live tickets, our template sets it to true. The endpoint also has its own rate limit, separate from the account-wide limit, so we size it against expected call volumes during design and prove it in performance testing.

Zendesk returns more than the flow needs: the tickets, a count, and paging properties such as next_page and previous_page. The data action's response configuration turns that raw response into a resolved response the flow can use. A translation map uses JSONPath to pick values out of the payload, here $.count and $.tickets. Translation map defaults supply a fallback when a JSONPath expression fails to resolve a value, though Genesys notes that null values do not fall back to defaults. Finally, a success template written in Velocity Template Language builds the output.

Our success template branches on the count. When the caller has no open tickets, it returns the count alone, and the flow offers to raise a new ticket. When tickets exist, it returns the count and the tickets, which the flow reads back to the caller or passes to the agent script. Genesys also provides Velocity macros for common shaping jobs, such as successTemplateUtils.firstFromArray to take the first item of an array, which suits a most-recent-ticket lookup. The results are written to participant data, so they travel with the conversation from the IVR to the queue and on to the agent's script.

Identification and verification is where integrations most often move data they never needed. Our rule is that the secret is checked, never stored where it can be read. The caller is identified by their number, through the static phone number lookup, or by their account number held in a custom field. Verification then uses a factor that does not sit in a readable Zendesk field: for example a one-time passcode sent to the customer's registered mobile number or email address, or knowledge answers checked by a dedicated verification service that returns only pass or fail. Anything the caller keys in is collected in an Architect secure flow, which Genesys designs for sensitive PCI and PII data.

Only the outcome reaches participant data, as a verified flag and the method used, so the agent sees a clear verified status and never the answer itself. Resilience gets the same attention. Every data action in a flow has success and failure paths, and we design both: a timeout or a Zendesk error routes the caller to an agent with a flag that the lookup did not complete, never into silence. Genesys now lets administrators set each action's execution timeout from 1 to 60 seconds, and recommends setting it one second longer than the flow's own timeout, which keeps IVR data dips responsive.

When the caller reaches an agent, the Genesys Cloud script is built from participant data the flow has already set, so there is no extra lookup while the call is ringing. The agent sees who is calling and their segment, the verified status, the IVR exit point, and the ticket the caller has just raised or the most recent open one, with a button that opens it in Zendesk. Credentials and traffic stay protected throughout: the integration authenticates with an API token, every request travels over HTTPS, and the Data Actions Performance views let us watch performance and failure rates once the integration is live.

Genesys also offers Genesys Cloud for Zendesk, an embedded client that places Genesys Cloud contact centre services inside Zendesk, with screen pop, scripts and interaction logs, and support for calls, callbacks, outbound dialling, email, messages and ACD voicemail. Genesys lists Zendesk licences including Zendesk Talk Partner Edition among its prerequisites. It is the natural choice when agents should live in Zendesk. Our pattern suits agents who work in the Genesys Cloud workspace and consult Zendesk as the system of record; the data actions integration that powers it does not depend on Zendesk Talk Partner Edition, and the same actions can serve an embedded deployment later.

On every integration of this kind, our Senior Business Consultant captures the journeys and the Zendesk fields they depend on, the Solution Architect records the design choices, including the Users API decision, in a design decision log and the Interface Control Document, Senior Developers build the actions to the Senior Platform Practice Lead's engineering standards with four-eyes peer review, and our Systems Integration Tester proves the failure paths: no match, two matches, no tickets, a timeout, an expired API token and a ticket created seconds earlier. We design, build and test integrations like this one for clients and systems integrators, and document them so that their own teams can support them.