Integrating Genesys Cloud CX and Salesforce: a data-action-led design

Picture a helpdesk line at 09:02 on a Monday. A customer rings about a case they opened last week. Everything about them is in Salesforce: the Contact record with their number, the Account it belongs to, the open Case, the comments added since, and a handful of fields the business added for itself, such as the customer's segment and preferred language. 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 record that already exists.

The question our client put to us was precise. How do we make Salesforce information available to callers and agents inside Genesys Cloud, and at the same time shape the Salesforce schema around what the contact centre needs? Our answer was to treat Salesforce as the system of record and Genesys Cloud as the system of engagement, and to join them with data actions: small, contract-defined API calls that Architect flows and agent scripts run at runtime. The IVR asks Salesforce who is calling, the agent sees the answer before they say hello, and the outcome of every call goes back to the record.

Good integrations start in the data model, not in the flow. Salesforce links its standard objects naturally: an Account has many Contacts, and Contacts and Accounts have Cases. That structure already answers most of the questions an agent asks. What it did not hold was the data the contact centre needed to drive the caller's experience, so in Object Manager we added custom fields to the Contact object under Fields & Relationships: a preferred language, a customer segment, and the flags the IVR reads. Each field was given the narrowest sensible type, a picklist rather than free text wherever the flow will branch on the value.

One naming detail matters to every developer who follows. Salesforce gives custom objects and custom fields an API name ending in a double-underscore suffix, __c, so a field labelled Preferred Language is read and written over the API as Preferred_Language__c. Data action request templates, SOQL queries and response translation maps must all use that API name, never the label. We record each field's label, API name, type and the flow decision that depends on it in the interface contract, so a later rename in Salesforce is caught as a breaking change rather than discovered as a silent lookup failure in production.

The Salesforce data actions integration in Genesys Cloud provides static actions, generated automatically when the integration is added, and lets you build custom actions of your own. We used both. The first step in the inbound flow is a Call Data Action that runs the static contact search by phone number, fed from Call.Ani. Genesys presents Call.Ani in E.164 format, and the integration searches Salesforce for exactly the number it is given, so we agreed a storage format for phone numbers with the Salesforce administrators before writing a single action. If the number finds no match, or finds more than one, the flow asks the caller for their account number and runs a second, custom lookup by account instead.

The default actions did not return everything the journey needed, so we customised and extended them. Our custom actions query by Contact Id for the most recent open Case, returning its number, subject and status, alongside the custom fields on the Contact. Each custom action has a request template, a translation map that picks values out of the raw Salesforce response with JSONPath, translation map defaults for values that may be missing, and a success template that must conform to the action's success schema. Arrays deserve particular care: we translate a list of records into the discrete values the flow will actually use, because a response that does not match its schema fails the action.

Every action in a flow has success and failure paths, and we design both. A timeout or a Salesforce error never strands a caller; the failure path routes them to an agent with a flag that the lookup did not complete, so the script can say so. Results are written to participant data with Set Participant Data, which persists across transfers between flows and travels with the conversation to the agent. One custom field changes the caller's experience immediately: the flow reads Preferred_Language__c and selects the matching text-to-speech voice, so a caller who prefers Australian English hears an Australian English voice from the first prompt after the lookup.

Identification and verification is where integrations most often leak data they never needed to move. Our rule is simple: the secret is checked, never shown. The caller's account number identifies them; their PIN, or any other knowledge-based answer, is collected in the IVR using Architect's secure flow capabilities, which Genesys provides for processing sensitive PCI and PII data through secure actions and secure variables, each marked with a key icon. The comparison happens on the Salesforce side, through a custom data action that sends the collected value for checking and receives a single result back: verified or not verified.

Only that outcome is written to participant data, as a Verified flag set to true or false, together with the method used. The PIN is never written to participant data, never stored on the call log record, and never passed to the agent script, so it cannot appear in an agent's screen, in interaction details or in an export. The agent sees a clear verified badge and can proceed with confidence; an unverified caller is routed with that status, and the script shows the agent what is still required. Genesys already notes that secured customer data cannot be assigned in a Set Screen Pop action; we go a step further and never move the secret towards the desktop at all.

When a caller chooses to speak to someone, our job as integrator is to give the agent an unfair advantage in the first second of the call. We work to a 5WH checklist: who is calling, what about, why now, when they last contacted us and where in the IVR they left. The Genesys Cloud agent script receives the participant data the flow set through script input variables, so the screen pop is assembled from data that is already on the conversation, with no extra lookup while the call is ringing. The layout itself changes with the payload: a verified caller with a matched record gets a different screen from an unmatched caller or a failed lookup.

The script shows a header that reinforces the nature of the call by its queue; the verified status as a coloured badge; the number dialled and the caller's number; the IVR exit point, which is a strong indicator of intent; the customer segment and other custom fields from the Contact; the most recent open Case with its subject and status; and contact details such as email, useful if the agent needs to move the enquiry to another channel. A single button opens the matched record in Salesforce, in a new tab, for the moments when the agent needs the full history. Outbound calls placed on behalf of a queue get their own script layout, so agents reaching out to customers can open Salesforce at the right record too.

An integration that only reads makes Salesforce a little less true after every call. So we close the loop. A custom data action creates a call log record against the Contact each time the customer contacts the centre, carrying the Genesys Cloud conversation ID and a link back to the interaction, plus the __c fields the business reports on. Salesforce users can see from the record that the customer called, when, and where to find the conversation, without leaving Salesforce. The same values stay on the conversation as participant data, so they are also available downstream in Genesys, for example to quality management.

The write-back pattern also powers self-service. A verified caller can add a comment to their open Case, or open a new one, without waiting for an agent. In our build, a voice bot flow captures a free-form subject and a description in the caller's own words; a custom data action creates the Case in Salesforce; the lookup is refreshed so the new Case is now the latest one on the account; and the caller is routed to a helpdesk team member who sees that Case in the screen pop. A caller who chooses to speak to someone arrives with the paperwork already done.

Credentials deserve the same discipline as data. Salesforce is retiring the OAuth username-password flow, and Genesys Cloud is deprecating the matching credential type for Salesforce data actions, in favour of a Salesforce (OAuth Client Credential Flow) type that uses a Connected App's client ID and secret and the organisation's My Domain URL. Genesys's migration guide recommends validating new credentials on a temporary integration with an imported action before updating the live one, because a credential change takes effect immediately. That is how we migrate our clients' integrations, and every new integration we build starts on client credentials.

Genesys offers several ways to bring the two platforms together, and the right one depends on where agents should work. CX Cloud from Genesys and Salesforce brings Genesys Cloud voice, digital and CRM data into Salesforce Service Cloud Voice through managed packages: Core Services, Voice, Digital and AI, WEM, External Routing and Outbound Campaign Management. Agents work in the Salesforce console. Screen pop is driven by a GC_SCREEN_POP participant attribute that an Architect flow sets to a Lightning page or record ID, and call attributes can be synchronised to Salesforce VoiceCall records through field mapping. Genesys notes that in CX Cloud, Salesforce Omni-Channel controls the interaction, so scripts that invoke transfers need review.

Genesys Cloud for Salesforce, the managed package that embeds the Genesys Cloud client in Salesforce, is built on Salesforce Open CTI. Genesys deprecated it with effect from 23 March 2026; it is now in maintenance mode, and it will retire with Open CTI on 28 February 2028. Genesys lists two migration paths: CX Cloud, if agents need to work inside Salesforce, or the Genesys Cloud user interface directly. The Salesforce data actions integration sits alongside both and is what our design is built on. It is not a desktop at all, but the API connection that flows and scripts use to read and write Salesforce data, and a data dip of exactly this kind is one of the sources Genesys lists for the GC_SCREEN_POP value.

Our pattern is the natural fit when agents work in the Genesys Cloud workspace and Salesforce is the system of record they consult, rather than the desktop they live in. It has no dependency on Open CTI, so the 2028 retirement does not touch it. It is not either-or: the same data actions, __c fields and participant data design carry straight into a CX Cloud deployment if the organisation later moves agents into the Salesforce console. On every engagement, our Senior Business Consultant captures the journeys and the fields they depend on, the Solution Architect records the choice 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 review, and our Systems Integration Tester proves the failure paths: no match, two matches, a timeout, an expired credential and a failed verification.