Handbook

Genesys Cloud data actions: the integration handbook

A detailed handbook for the people who build and run the Genesys Cloud integration layer. It covers the eight integrations, contracts, request configuration, Velocity and escaping, response translation, credentials and certificates, timeouts and limits, rate limits and caching, failure design, testing, functions, Architect and Scripts, environments, permissions and governance. Checked against Genesys sources on 15 November 2026.

By Dave Tidwell, Managing Director31 min read

In short

  • A data action is where another system's availability becomes your customer's experience, so design every failure path.
  • Contracts cannot change after publishing, and there are 500 actions per organisation: design wide, catalogue everything.
  • Escape every interpolated input, use silent notation for optional values, and remember nulls do not use defaults.
  • Timeouts differ by caller: 60 seconds in flows, 20 in Scripts and the API; set actions one second longer than the flow.
  • Respect the shared concurrency and rate limits with one token, a data table cache and no polling from call flows.

01

What data actions are, and where they are used

This handbook is for the people who design, build and run the integration layer of Genesys Cloud: integration architects, developers, flow authors, script designers and the owners of the systems on the other end. Every statement about Genesys Cloud comes from Genesys's documentation, listed in the sources and checked on 15 November 2026. Where something is our own practice, it is labelled QVCCS practice. Our Architect handbook covers data actions from the flow author's side; this handbook covers the actions themselves.

1.1 The integration backbone

Genesys defines data actions as a way to access data from a web service and perform tasks with it, such as adding customer data to agent scripts. More widely, the data actions integrations gather data from external systems, act on data in third-party systems, invoke AWS Lambda functions, call the Genesys Cloud Platform API or work with JSON-based web services, and the data is then used to make routing decisions in Architect, present information to agents in Scripts, or act on it in other ways.

Almost every meaningful contact centre feature touches one: caller identification, a balance in the IVR, a screen pop, opening a case, routing on order status, writing a disposition back to the CRM. That makes data actions the point where another system's availability becomes the customer's experience. If the CRM is slow, the caller waits; if it is down and the failure path is unhandled, the call fails.

They are also low-code, which cuts both ways: something a business analyst can configure in an afternoon can be configured badly in an afternoon, with no review, no load test and no error path. Part 14 is about who owns this layer.

1.2 Outbound and synchronous

A data action is outbound and synchronous: Genesys Cloud asks another system for something and waits. Inbound, event-driven integration is a different mechanism. The webhook for events integration converts incoming webhook messages into custom events that can trigger actions or workflows. There is no such thing as a webhook data action, and the distinction is worth settling early in discovery.

1.3 The two main consumers

Where data actions are used
ConsumerHow it calls a data actionConstraint that matters
ArchitectThe Call Data action inside a task, for routing, self-service or write-backRuns inside a live interaction, with Success, Failure and Timeout paths
ScriptsData Actions.Execute Data Action on a button or page loadNot available until the Data Actions script property is enabled
Other callersWorkflows, workitem flows and applications calling the execute endpointThe same action, with different timeouts (part 8)
  • Genesys is explicit that the Call Data action does not evaluate the data it retrieves; later actions such as Decision or Switch do. The action fetches, the flow decides.
  • Many tickets that say the data action is broken turn out to be a missing Decision step, or a Decision written against a field the output contract shaped differently.

02

Integrations, static and custom actions, and naming

Genesys provides a fixed set of data actions integrations, two kinds of action and a naming rule with a consequence for every flow author.

2.1 The eight integrations

Genesys Cloud data actions integrations
IntegrationWhat it reachesStatic actions
AWS LambdaA Lambda function in your own AWS accountNo
FunctionYour Node.js code, deployed by Genesys Cloud to AWS LambdaNo
Genesys CloudThe Genesys Cloud Platform API, through a Genesys Cloud OAuth clientDocumentation differs (2.2)
GoogleGoogle Cloud FunctionsNo
Microsoft Dynamics 365Dynamics 365 recordsYes
SalesforceSalesforce recordsYes
Web servicesAny JSON-based web serviceYes
ZendeskZendesk tickets and usersYes
  • ServiceNow is not on the list. It appears in Genesys documentation as a CRM integration and a knowledge connector, but ServiceNow data reaches a flow through the web services integration against ServiceNow's API, or through an AppFoundry product.
  • One Architect article also names Adobe alongside these integrations; treat Genesys's list of eight as authoritative and confirm anything else in your organisation.

2.2 Static and custom actions

Static actions are preconfigured by the integration; default actions are created automatically when you add it. Custom actions are created by administrators and can retrieve, update or create any data, through request and response schemas you define. Genesys's concepts page lists AWS Lambda, Function, Genesys Cloud and Google among the integrations without static actions, while its Genesys Cloud integration page mentions automatically generated static actions, so check in your organisation before relying on one.

For Dynamics 365, Salesforce and Zendesk static actions, the inputs shown in Architect depend on the action; a lookup by phone number presents a PHONE_NUMBER field. For custom actions, the inputs come from the request schema you wrote. Only custom actions can be deleted. Genesys also notes that data actions cannot perform conversation operations such as transfers, recording or disconnection.

2.3 Choosing an integration type

The choice is mostly about who owns the logic. Web services is the default: the remote system exposes an API and you shape the contract in Genesys Cloud. Genesys Cloud is for calling the platform's own API, such as queue statistics. AWS Lambda or Function is for logic a single HTTP call cannot express; Genesys's examples are format conversion such as XML to JSON, multi-step API calls and calling several endpoints in one invocation. The CRM integrations add vendor static actions.

2.4 The integration name is the category name

Genesys states that integration names are also the category names used across Genesys Cloud, and categories group the actions authors see in Architect and Scripts. Rename an integration and you change the label in front of every author. Genesys's advice when renaming is to use unique names, so integrations and their actions can be told apart. That matters wherever there are several integrations of one type: one per region, one per business unit, or a test and production pair.

03

Anatomy of a custom action, and its contracts

A custom action is a contract plus a configuration, under a name and a category. Understanding the sequence it runs in explains most of the warnings in this handbook.

3.1 The parts of an action

The parts of a Genesys Cloud custom data action
PartWhat it holds
Input contractThe JSON schema of the inputs the caller provides
Output contractThe success schema the resolved response must match
Request configurationMethod, URL template, request body template and headers
Response configurationTranslation map, translation map defaults and success template
SettingsName, category, timeout and whether the action handles secure data

3.2 What happens when an action runs

  1. A caller executes the action with a JSON body of input values.
  2. The action service replaces references to those inputs throughout the configuration, including the URL template and request template.
  3. The resulting request is sent; the request template becomes the body.
  4. The remote system's reply is the raw response.
  5. The translation map extracts values from it by JSONPath into named aliases.
  6. The success template assembles an output, which must match the success schema.
  7. The resolved response returns to the caller.

3.3 Contracts cannot change after publishing

Genesys states it plainly: you cannot change the contracts after you publish the action, and contracts do not support the $ref keyword. Adding a field to a published action's output is not an edit; it is a new action, and every flow, script and workflow using the old one must be updated. When you delete an action, Genesys warns that you must update references to it in flows and scripts yourself. Contract changes therefore need a change request and a migration plan.

3.4 Input contract rules

  • The input contract is one flat object of key-value pairs, limited to string, integer, number, Boolean and null; nested objects are not supported. To send a JSON object, pass it as a string input and escape it into the body.
  • Property names must start with a letter and contain only letters, numbers, hyphens or underscores.
  • Do not use the reserved names orgId, integrationId or rawRequest.
  • Genesys recommends the Simple input method over writing JSON Schema by hand.
  • Shared schema libraries that use $ref must be expanded into self-contained schemas first.

3.5 Output contracts and flattening

The output contract does not support nested arrays. When testing, Genesys advises keeping Flatten output selected, because most Genesys Cloud applications use flattened data. Scripts add a sharper limit: Genesys states that scripts currently cannot read data from a JSON array. The same action can therefore work in a flow and fail in a script while being entirely correct.

The success schema is also behind a confusing failure: the web service returns 200, the data is present, and the action takes the Failure path because the resolved output does not match the schema. Nothing is wrong with the remote system; the contract and the translation disagree.

04

Request configuration and HTTP methods

Four fields define the request: requestUrlTemplate, requestType, requestTemplate and headers. Genesys documents a few behaviours here that waste a lot of time when missed.

4.1 The four request fields

requestUrlTemplate is the remote endpoint, or the ARN of a Lambda function for the AWS integration, and supports Velocity substitution; if it is an HTTP endpoint, it must be HTTPS. requestType is the HTTP method. requestTemplate is the body, as a Velocity template. Headers are key-value pairs added to the request, and their values also support substitution. After saving, the request template is stored as a separate resource, referenced by a requestTemplateUri, which matters if you build your own tooling.

4.2 Three behaviours that waste time

  • Authorisation may already be handled. Genesys says that if you rely on the integration's credentials to authorise, do not add an Authorization header yourself, because the integration populates it. A duplicate header can produce a 401 that only appears against the production service.
  • The Accept header, if set, must be a JSON media type. Genesys documents that setting it to text/html causes errors in testing.
  • The web service sees real values. For user-defined credentials, Genesys notes that although field names are redacted in Genesys Cloud, the actual values arrive at your web service, including in the URL if you put them there.

4.3 HTTP methods: what the documentation says

Genesys's pages differ, so set out what each says. The request configuration page says the available request types include POST, PUT and PATCH, and that request templates define the body of those requests. The requirements page says a web service must support GET, PUT, POST, PATCH or DELETE, and the Genesys Cloud integration uses GET, PUT, POST or PATCH. Genesys's own examples use GET, and the request configuration page itself notes that GET requests do not use request templates, showing ${input.rawRequest} as the default.

Read together, GET is clearly supported, without a body. DELETE appears only on the requirements page, so confirm it with Genesys before a design depends on it. For the AWS Lambda and Google integrations, Genesys says to use POST so that the request body is sent.

05

Velocity, escaping and macros

Genesys uses the Apache Velocity Template Language for substitution. Velocity is valid in four fields: requestUrlTemplate, headers, requestTemplate and successTemplate. Most reported failures trace back to two things in this part: null handling and escaping.

5.1 Formal and silent notation

Genesys documents two notations. Formal notation, ${variable}, outputs the variable's name if the value is null. Silent formal notation, $!{variable}, outputs an empty string. So with formal notation, a missing surname does not become empty: the literal text of the reference appears in your JSON body, and the remote service receives nonsense or fails to parse it, while nothing errors in Genesys Cloud.

Genesys's resiliency blueprint is explicit: use silent formal notation for non-required string inputs in a JSON request body. Inputs are referenced as ${input.FIELD}, and translation map aliases appear in the success template as plain references, which Genesys describes as treating everything else in the template as literal.

5.2 Escaping: the commonest cause of failure

Genesys prints the same warning on several pages: escape any use of input or output variables within requestTemplate, successTemplate or requestUrlTemplate, because variables with special characters that are not properly escaped make data actions fail at execution.

Which escaping macro to use where
Where the value goesMacroNote from Genesys
Inside a JSON bodyesc.jsonString (or esc.jsonEncode)Escapes quotes and other characters by JSON rules
In a URL path or templateesc.uriEncode or esc.urlGenesys says uriEncode should be used for the URL template; spaces become %20
Form-encoded valuesesc.urlFormEncodeSpaces become +; Genesys says it is most likely not for the URL template
Optional query parametersurlTool.optionalQueryParamAdds the parameter only when a value exists
Neveresc.javascriptGenesys warns it can create invalid JSON that breaks an action
  • Using the wrong URL macro can turn spaces into plus signs that the remote service reads literally, so a search silently returns nothing rather than failing.
  • Genesys's own worked example wraps each name input in esc.jsonString inside the request body.

5.3 Other useful macros

Beyond escaping, Genesys documents a math library, encoding.base64 (used for Basic authentication headers), esc.jsonDecode, Java string methods, Dynamics and Salesforce helpers, and macros for literal characters, including a dollar sign, which Velocity would otherwise read as a reference. Two success template helpers solve recurring problems.

successTemplateUtils.firstFromArray extracts the first element of an array, and takes an optional second value returned when the array is empty. That second value is what lets a flow tell not found from service broken: without it, an empty result can fail schema validation and take the Failure path. Genesys notes that values already extracted by JSONPath need no further escaping. successTemplateUtils.moveKeysIntoArrayOfObjects reshapes response data.

06

Response configuration: translation maps and templates

Genesys explains the response side as a pipeline: translation maps and success templates convert raw responses into resolved responses that match the success schema, because raw responses do not necessarily match it. This is where an action becomes usable, and where its most frustrating failures live.

6.1 Translation maps

A translation map holds key-value pairs mapping alias names to the values found by JSONPath expressions. Genesys's examples lift a list of search records into one alias, and lift four scattered fields of a payment response to the top level. Its reasons to use translation are the design checklist: the response contains several objects that must be grouped, contains arrays you want as discrete values, includes more than you want to return, or needs a guaranteed order.

Alias names follow the same rules as input names. Where a source key contains a space, Genesys shows using brackets and single quotes in the JSONPath. And one integration behaves differently: Google Cloud Functions return a stringified JSON response, which actions convert to JSON before applying translation maps.

6.2 Defaults, and the null trap

Translation map defaults set a value used when a JSONPath expression fails to resolve. Genesys adds the sentence that catches people: null values do not fall back to defaults.

When a translation map default applies
Remote responseJSONPath resultValue used
Field absentDoes not resolveThe default
Field present with value nullResolves to nullNull, not the default
Field present and emptyResolves to an empty stringThe empty string
  • If the success schema does not allow null for that field, the resolved response fails validation and the action takes the Failure path, although the service answered correctly.
  • That is the mechanism behind the commonest maddening symptom: works in testing with one record, fails for a minority of real customers whose records contain a null.

6.3 Be flexible in translation

Genesys's resiliency blueprint makes this a principle: if the response translation encounters an error, the action takes the failure path, so make the translation handle every scenario, including missing properties. A translation that cannot survive an unusual response turns a data oddity into a contact centre incident.

6.4 Success templates and passing the response through

The success template uses Velocity to assemble the output from translation map aliases, and the result must conform to the success schema. Where the remote response already matches the schema, Genesys documents a one-line success template, ${rawResult}, which passes the whole response through without a translation map.

If you control the API at the other end, shaping it to match your contract and passing it through removes a whole class of defects. It is the wrong choice for third-party APIs you do not control, whose changes then flow straight into your contract, and for responses carrying data the consumer should not see.

07

Credentials, certificates and the network

Every web services action depends on a credential configured on the integration and on a certificate chain someone else maintains. Both have documented one-way doors.

7.1 Credential types

Credentials are configured on the integration, not per action. For web services there are three types. Basic Auth sends a Basic authentication header with every request. User Defined lets you add named fields, referenced in any action through the credentials keyword. User Defined (OAuth) adds named fields and creates a custom auth action, which obtains a token; its response is then available to every other action through the authResponse context, typically as an Authorization header built from the token type and access token.

When you test an auth action, Genesys shows the response shape with values redacted. If an auth endpoint cannot handle chunked transfer encoding, Genesys says to add a Transfer-Encoding: buffered header.

7.2 The warning about changing credential types

Genesys warns: do not change a credential type after configuring the integration and publishing actions, because it could break actions in use; to migrate an active integration to a new credential type, contact Genesys Cloud Customer Care. Moving a live estate from API keys to OAuth is therefore not a configuration task. Decide the credential type at design time, alongside the contracts.

Two integration-specific notes. For Salesforce, Genesys flags that Salesforce has announced end of life for the OAuth username-password flow, and recommends the client credentials flow for new integrations and migrating existing ones. For the Genesys Cloud integration, the OAuth client's scope decides what every action on it can do, which makes it a high-value credential for the secrets register.

7.3 Endpoint requirements

Genesys's requirements for a web service are specific: JSON-based calls; no, Basic, user-defined or user-defined OAuth authentication; an HTTPS endpoint on port 443, with no other ports supported; TLS 1.2 or 1.3; a certificate from a publicly trusted authority; and all intermediate certificates presented during the TLS handshake. Its troubleshooting page names the two common failures, a self-signed or untrusted root and a missing intermediate, and suggests pointing an external HTTPS checker at the endpoint. A missing intermediate shows in an external scanner but not in an internal browser, which is why an endpoint works from a laptop and fails from Genesys Cloud.

7.4 Mutual TLS and certificate rotation

Only web services data actions support mutual authentication. You configure your service to trust certificates from the private certificate authority for your Genesys Cloud region, choosing Genesys Cloud or DigiCert as the authority; the certificates include a revocation list and are rotated automatically each year. Genesys recommends trusting the root CA, and warns that thumbprinting may leave you with outdated certificates when it rotates them.

Network allowlisting changed in November 2022: Genesys Cloud now automatically allows IP addresses that originate from data actions integrations, so administrators no longer need to add them to the allowlist. Your own firewall and any proxy or mutual TLS layer remain your responsibility, as our network and firewall guide explains.

08

Timeouts and limits

Timeouts and organisation limits decide how a data action behaves under load. Several are easy to get backwards, and two limits are shared by every action in the organisation.

8.1 Timeouts depend on the caller

Data action timeouts by context (from Genesys)
ContextTimeout
Call flowDefaults to 60 seconds; an administrator can set 1 to 60 seconds on the action
Scripts and the Public API20 seconds, after which the action times out with an error
Test mode19 seconds, so that a useful report can be returned
Genesys Cloud Function code1 to 15 seconds for the function itself
  • An action tuned to 45 seconds because it works in the IVR will fail in a script, a workflow or any application calling the execute endpoint.
  • After its timeout, an execution is removed from the concurrency limit, so a slow endpoint occupies capacity for as long as it runs: a capacity problem as well as a latency one.

8.2 One second longer, not shorter

Genesys's best practice is easy to get backwards: set the data action's timeout one second longer than the flow's configured timeout. That way the flow's own timeout logic runs cleanly and the action does not carry on processing after the flow has given up, which also protects the concurrency limit.

8.3 The limits

Genesys publishes data action limits on its Developer Center limits page. These are the values we read on 15 November 2026; two are configurable, so check your own organisation before designing to a number.

Data action limits (Genesys Developer Center, read 15 November 2026)
LimitValueConfigurable
Actions per organisation500No
Actions per integration100No
Concurrent action executions50Yes
Concurrent function executions (a subset of the above)25Yes
Requests per minute2,500Yes
JSON depth of nested objects and arrays50No
HTTP response size15,000,000 bytesNo
Function response size750,000 bytesNo
Lambda response size6,000,000 bytesNo
Lambda request context3,583 bytesNo
Function configuration, publish and delete requests1 per secondNo

8.4 What the limits mean in practice

500 actions per organisation and 100 per integration are a real ceiling, shared across every integration, and contracts that cannot change plus deletions that need manual reference clean-up make it easy to exhaust. One action per interface, used by many flows, is sustainable; one action per flow is not.

50 concurrent executions is the limit that bites at scale, because every action in the organisation shares it. Genesys's resiliency blueprint warns that if you expect more than a couple of hundred interactions per minute, each calling at least one data action, overall execution may be affected by rate limits in the remote service and in Genesys Cloud. A peak, a dialler burst or a retry storm can reach the ceiling in seconds, and then every action queues, including those on live calls.

The 3,583-byte Lambda request context is the ceiling on what headers become when passed to a function. Genesys notes that this context cannot carry the certificates configured in credentials for function actions, which must be passed in the request body instead.

09

Rate limits and caching

Genesys's resiliency blueprint is unusually direct about rate limits, and pairs the warning with a documented caching pattern. Together they are the most useful architecture guidance for this layer.

9.1 What Genesys says about rate limits

The blueprint explains that while you can run 2,500 data action executions per minute, a data action calling a Genesys Cloud API can make only 300 requests per OAuth token before the Platform API rate-limits that token. The effective ceiling for an action calling Genesys Cloud is the lower figure.

It also warns against workarounds. Some developers try to avoid limits with extra OAuth clients or tokens; Genesys says hitting rate limits is a signal that you are not using its APIs correctly, for example not caching or polling too much. Circumventing limits can affect the whole organisation, as services further down the stack begin rate-limiting, up to a partial or complete contact centre outage. Its instruction is to respect the per-token limit and use a single token per integration, and it notes that Genesys reserves the right to shut down an OAuth client causing platform instability. Its framing is that rate limits are a good thing: they increase availability and stop any single entity causing an outage.

9.2 The caching pattern Genesys publishes

The blueprint sets out the requirements: a separate cache entry for each unique set of request parameters, a way of telling when data is stale, and a store that is fast, highly available and not rate-limited when read in a flow. Its answer is a Genesys Cloud data table. Reading from a data table has much higher limits than running data actions, while writes go through data actions and the Platform API and count against API limits. Genesys adds that in most cases cached data can be one to five minutes old and still meet customer experience objectives.

Reads are cheap and writes are not, so entries are written rarely and read constantly. The flow looks up the table first; if there is no entry, or its timestamp is older than the refresh interval, it runs the action, uses the result and writes it back. Genesys's example caches an on-queue agent count per queue with a five-minute interval, because the routing decision only needs to be approximately right.

9.3 Deciding what to cache

  • Per interaction, such as an authenticated balance or a one-time token: never cached.
  • Per customer and tolerant of age, such as an address or entitlement: cached with a timestamp.
  • Global, such as queue state, agent counts or opening hours: cached aggressively, keyed by what is looked up.

10

Designing for failure, and testing safely

This part separates an action that demonstrates well from one that survives a bad day at the CRM. Genesys's resiliency blueprint names the failure modes and the safeguards; its test tool has a behaviour every security team should know about.

10.1 Four ways actions fail

  1. Bad user input: for example, an incorrect account number the downstream service rejects.
  2. The service does not respond: an unexpected error, a timeout or a network problem.
  3. Flow logic or a misconfigured action: for example, an unset variable or an out-of-range collection.
  4. Service-imposed rate limits.

10.2 The safeguards

  • Handle all output paths. Each Call Data action has Success, Failure and Timeout; Genesys's example plays account data on Success, re-prompts on Failure and goes straight to a queue on Timeout. Define the behaviour for all three.
  • Remember that Success means no errors occurred, not that the data is what you hoped for. A lookup that finds nothing is a Success, so handle not found inside the Success path.
  • Put a reasonable upper limit on retries. Genesys warns that with locally deployed edges, call flows without a retry limit can spike the edge's CPU and affect every customer it serves.
  • Validate before calling. Genesys's example: if an account number must be ten digits, check it has ten digits before running the action.
  • Customise flow error event handling, which by default plays a message and disconnects, to route to a queue or another task.
  • Escape inputs and use silent notation (part 5), and make response translation flexible (part 6).

10.3 Test the failure paths too

The blueprint does not say to test failures, and a Success path tested against a good record proves very little.

10.4 The Test tab shows real data

Genesys warns not to include sensitive data in an action, because the test displays the entire request and response payload, including sensitive data. Credential values are redacted when testing user-defined and OAuth types; business data is not. A test against a real customer record puts their details on screen, and the payload may end up pasted into a support case. Test against synthetic records.

10.5 What testing can and cannot prove

  • The test stops at the first failure, so fix errors in order.
  • A JSON test mode lets you send fields as empty strings, as null or omitted altogether, which is how you reproduce the null cases in part 6.
  • Test mode times out at 19 seconds, so slow actions behave differently from production.
  • Tests hit the real endpoint. Testing a write action against production creates real records.
  • If an input contract is complete but no fields appear, Genesys's advice is to refresh the browser.
  • Script preview cannot simulate data actions: it shows which action would run and assigns no data.
  • For Genesys Cloud Function actions, the test returns the last 4 KB of console log output, and those logs are available only during testing.

11

Genesys Cloud Functions and AWS Lambda

When a data action needs logic rather than a single call, it can run code. AWS Lambda invokes a function in your own AWS account, referenced by ARN. The Function integration lets you upload custom code that Genesys Cloud deploys to AWS Lambda on your behalf; it arrived in January 2025 for format conversions, multi-step API calls and several endpoints in one invocation.

11.1 Choosing between them

A Genesys Cloud Function needs no AWS account, cross-account permissions or separate deployment pipeline, which makes it the quick route. A Lambda in your own account gives you the full AWS toolset, your own security boundary and observability, and your own availability dependency. The choice is usually organisational, and belongs with the client's architecture forum.

11.2 Function packaging and runtime

  • Code runs on Node.js; supported runtime versions are listed in the data actions requirements and release notes, and Genesys introduces newer versions and deprecates older ones over time.
  • Code is uploaded as an unencrypted ZIP file of no more than 256 MB, with a handler in the form path.exportName.
  • The function timeout is 1 to 15 seconds, much shorter than the action timeout.
  • Genesys recommends a packaging framework such as Serverless Framework to get the ZIP structure right.

11.3 Properties that are really audit and availability issues

  • Genesys states that code in the ZIP file is not scanned for viruses, so code review, dependency scanning and a build pipeline are your controls.
  • You cannot download the ZIP file from Genesys Cloud. Your source repository is the only copy.
  • Uploading a new ZIP replaces the existing one, with no versioning or rollback in the platform.
  • Function data actions do not support import, copy or export, so promotion between environments depends on your own pipeline.

11.4 Context passed to functions

Headers become context items for the function, and Genesys includes several context attributes automatically, such as conversation, organisation, correlation and user identifiers. Inputs from the request template arrive in the function's event parameter. The correlation identifier is what links a function's log line to an interaction, so log it on entry.

A Lambda in the client's own account is on the critical call path. The client's AWS team must know it, with alerting, quotas and a runbook to match.

12

Phone numbers, Architect and Scripts

This part covers the consumers: the lookup key that quietly breaks voice journeys, and the specifics of using data actions in Architect and in Scripts.

12.1 Phone numbers: the quiet failure

Genesys documents phone number search behaviour per integration, and each differs. Genesys Cloud presents the caller's number in Call.Ani in E.164 format, such as +13175550123, and Architect shows it as a tel: value. Salesforce searches for the exact number in the PHONE_NUMBER field; Genesys warns that the number in Salesforce and the one searched for must be identical in digits and format, and that stored country codes cause issues. Zendesk ignores punctuation but requires all digits to match, so Genesys advises searching for all possible formats. For Dynamics, Genesys shows building the CRM's own format in the flow from substrings of Call.Ani.

The failure is invisible: the action succeeds, the lookup finds nothing, the caller is told their account cannot be found and goes to a general queue, and the misroutes look like a routing problem rather than an integration one. Genesys's own test is to search in the CRM and check the results match what you expect.

12.2 Data actions in Architect

In a task, the Call Data Action comes from the Data category of the toolbox; the integration appears as its category and you choose the action, map inputs from flow variables and receive outputs as variables. Genesys's examples route on data retrieved from Salesforce with GetContactByEmail, or retrieve queue information from an external system. The action does not evaluate what it retrieves, so the flow author owns everything after it: branch on Success, Failure and Timeout, branch again inside Success for found and not found, validate inputs first, set timeouts coherently, and treat every action in the call path as a cost in latency, concurrency and failure surface.

For sensitive values, Genesys provides the Get Secured Data action with its own paths. And knowledge retrieval in Architect looks similar but is a separate subsystem: a bot looking up an order uses a data action; a bot answering a policy question uses knowledge, as our knowledge handbook explains.

12.3 Data actions in Scripts

Scripts use Data Actions.Execute Data Action from any component that supports actions, or as a page load action, which is the usual screen-pop mechanism. Genesys notes that data actions are not available by default: enable the Data Actions script property first.

Permissions for data actions in Scripts (from Genesys)
WhoNeeds
Script designer adding an actionView and Execute only; Add, Edit and Delete are needed only to manage the data source itself
Agent using the scriptIntegrations > Action > View, and Bridge > Actions > Execute
  • Scripts cannot read data from a JSON array (part 3).
  • Script preview cannot run data actions, so test in a real interaction.
  • Remember the 20-second timeout for Scripts (part 8).

12.4 Page load or button

A page-load action is an agent experience decision: if the lookup takes three seconds, every agent waits three seconds on every call, which shows up in handle time.

13

Environments, permissions and the API

Data actions move between environments as JSON, which is simple and hides a secrets problem. Their permissions are a small set, one of which is broader than it looks.

13.1 Copy, import and export

Copy Action works within the same integration. To reuse an action elsewhere, or in another organisation, export its contracts and configuration as JSON and import them. Genesys warns twice: remove sensitive data such as hard-coded credentials or API keys before exporting, and redact it before sending an exported file to anyone. Credentials held in the integration's configuration do not travel with an export, which is a good reason never to put secrets in templates. Genesys Cloud Function actions do not support import, copy or export.

Genesys's resiliency blueprint shows the practical sequence for promoting an action with a flow: import the data actions in the admin interface, import the flow in Architect, publish it with Archy, and update the imported actions' request URLs with the new environment's data table ID. That last step generalises: endpoint URLs, data table IDs and integration names differ by environment and must be listed.

13.2 Permissions

Counted from Genesys's published API definition on 15 November 2026, there are 12 integrations permissions and 2 bridge permissions behind the 28 operations under the data actions API.

Data action permissions (from Genesys's API definition)
PermissionControls
integrations:integration add, edit, delete, viewThe integration itself, including its credentials
integrations:action add, edit, delete, viewAction definitions, drafts and publishing
integrations:action:executeRunning an action, including in test
integrations:actionFunction view, editGenesys Cloud Function code and configuration
integrations:actionCertificate:viewMutual TLS certificates and trust store
bridge:actions view, executeThe older Bridge action permissions; execution accepts either execute permission
  • Genesys's minimum for an integration administrator is Integrations > Integration Edit and View, and Integrations > Action Add, Delete, Edit, Execute and View.
  • Genesys notes that selecting all permissions under Integrations > Action grants all current and future action permissions. Prefer the explicit five for standing roles.

13.3 Two permissions with wider consequences

The execute permission is a data access permission: its holder can run any action with any input, which can be a route to customer records beyond what that person could see in the CRM. Agents need it for scripts, so its real reach depends on which actions exist. integrations:integration:edit reaches the integration configuration where credentials live; separate it from day-to-day action authoring.

The API exposes a draft lifecycle for actions, with endpoints to create, validate, publish and test a draft, and an execute endpoint for real runs. If you automate, drive that lifecycle rather than patching published actions.

14

Governance, design and what goes wrong

Data actions are the layer most likely to be built by one person, used by forty, and owned by nobody. The failures are rarely technical.

14.1 The action catalogue

Three documented facts make an action inventory essential: the ceiling of 500 actions per organisation and 100 per integration, contracts that cannot change after publishing, and deletions that require you to find every reference yourself.

14.2 Three owners

The action owner builds and changes actions and owns the contract. The consumer owner, the flow author or script designer, owns the error paths and the customer experience when an action fails. The service owner runs the system at the other end and owns its availability. The third is the one most often missing: nobody told the middleware team that their endpoint is on every call, so there is no alerting, and a quiet degradation appears as an unexplained rise in abandoned calls.

14.3 A note on licensing

Genesys's summarised plan comparison (dated 3 November 2026 when we checked) lists CRM integration, its agent interface inside CRMs such as Salesforce, ServiceNow, Microsoft Dynamics and Zendesk, as an add-on for every CX tier. It does not list data actions as a separate line, so confirm entitlements for a given design with Genesys. QVCCS sells no licences and quotes no prices.

14.4 Designing the integration layer

Decisions to make before building (QVCCS practice)
DecisionWhat constrains it
One middleware layer per system, or direct endpoints100 actions per integration, unchangeable contracts, one place to secure
Integration type per systemThe eight integrations; ServiceNow is not one
Credential typeCannot be changed on a live integration without Genesys Customer Care
Response shapeJSON only; pass through with rawResult where you control the API
Endpoint postureHTTPS on 443, TLS 1.2 or 1.3, publicly trusted certificate, full chain
Timeout budget per journeyCall flow up to 60 seconds, Scripts and API 20, functions 1 to 15
  • Then design each contract once: naming rules, no reserved words, optional inputs that are truly optional, output shaped for every consumer, and not found representable without an error.
  • Build to a standard: silent notation, escaping everywhere, defaults with the null caveat understood, flexible translation, and no credentials in templates or URLs.
  • Prove it fails well: all three paths exercised, an outage test, a bad-data test, flow error handling confirmed, and peak load checked against the concurrency limit.

14.5 Eighteen things that go wrong

Common data action problems, causes and fixes
SymptomLikely causeFix
Fails at execution, fine in designAn unescaped input with a quote or special characteresc.jsonString in bodies, esc.uriEncode in URLs (part 5)
The body contains the literal text of an input referenceFormal notation with a null valueSilent notation for optional values (part 5)
Works in test, fails for some customersThe service returns null, and nulls do not use defaultsNullable schema fields or handling in translation (part 6)
The service returns 200 but the action failsThe resolved response does not match the success schemaAlign translation and schema (parts 3 and 6)
Invalid JSON errors for valid JSONThe service does not support chunked transfer encodingAdd a Transfer-Encoding: buffered header (14.6)
401 only in productionA duplicate Authorization headerRemove it when the credential type handles authorisation (part 4)
Certificate errors, though it works from a laptopSelf-signed or private CA, or a missing intermediatePublicly trusted certificate and full chain; check externally (part 7)
Lookups find nothing for real callersThe caller's number format differs from the stored formatAgree the format, test with real formats, add a fallback key (part 12)
Flows or scripts cannot see returned dataArrays with flattening, or scripts reading arraysReturn scalars for script consumers (part 3)
Fails in a script or workflow but not the IVRScripts and the API time out at 20 secondsSet timeouts for the shortest consumer (part 8)
Random actions fail at peakThe shared limit of 50 concurrent executionsShorter timeouts, caching, fewer calls per interaction (parts 8 and 9)
Rate-limit errors after adding OAuth clientsWorking around rate limits instead of fixing usageOne client and token, caching, redesign (part 9)
Mutual TLS broke after a rotationA pinned thumbprintTrust the root CA (part 7)
A field cannot be added to a live actionContracts cannot change after publishingNew action and reference migration; design contracts wider (part 3)
The wrong integration was chosen in a flowTwo integrations with similar namesName by system and market; never reuse names (part 2)
Customer data visible in a support sessionTest shows full request and response payloadsTest with synthetic records (part 10)
Function code lost or cannot be promotedZIPs cannot be downloaded, and function actions cannot be exportedDeploy from version control through a pipeline (part 11)
Calls drop during a CRM outageFailure and Timeout paths not designed, or default error handlingDesign all three paths and customise flow error handling (part 10)

14.6 The most misleading error

Genesys documents that by default it sends data actions with chunked transfer encoding, and that web services which do not support it return incorrect errors, such as invalid JSON even when the body is valid. Setting Transfer-Encoding to buffered makes Genesys Cloud send a Content-Length header and the whole body in one piece. Because the symptom points to serialisation rather than a transport header, put it first in any troubleshooting guide for a service desk.

Questions

Common questions

Can I change a Genesys Cloud data action's contract after publishing it?

No. Genesys states that you cannot change the contracts after you publish an action. To add or change a field you create a new action and update every flow, script and workflow that used the old one; Genesys's documentation does not offer a reference search, so keep a catalogue of each action's consumers from the start.

Why does my data action fail even though the web service returned 200?

Usually because the resolved response does not match the success schema. A common cause is a null value: translation map defaults apply only when a JSONPath finds nothing, and Genesys states that null values do not fall back to defaults. Allow nulls where absence is real, or handle empty results in translation.

How long before a Genesys Cloud data action times out?

In call flows the default is 60 seconds, configurable from 1 to 60 per action. In Scripts and through the Public API, actions time out after 20 seconds, and in test mode after 19. Genesys recommends setting the action's timeout one second longer than the flow's timeout so the flow's own timeout path runs cleanly.

What are the Genesys Cloud data action limits?

On Genesys's Developer Center limits page, read on 15 November 2026: 500 actions per organisation, 100 per integration, 50 concurrent executions (configurable), 2,500 requests per minute (configurable), JSON depth of 50, and an HTTP response limit of 15,000,000 bytes. Check your own organisation, because the configurable limits can differ.

Is there a ServiceNow data actions integration?

No. Genesys's data actions integrations are AWS Lambda, Function, Genesys Cloud, Google, Microsoft Dynamics 365, Salesforce, web services and Zendesk. ServiceNow appears in Genesys documentation as a CRM integration and a knowledge connector; to use its data in a flow, call its API through the web services integration or use an AppFoundry product.

Why do I get an Invalid JSON error when my JSON is valid?

Genesys documents that it sends data action requests with chunked transfer encoding by default, and that web services which do not support it can return misleading errors such as invalid JSON. Add a Transfer-Encoding: buffered header to the action so Genesys Cloud sends a Content-Length header and the whole body at once.

Sources

  1. About the Genesys Cloud data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  2. About integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  3. About the data actions integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  4. About the Genesys Cloud Function data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  5. About webhook for events – Genesys Cloud Resource Centerhelp.genesys.cloud
  6. About the Zendesk data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  7. Add a data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  8. Add configuration to custom actions for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  9. Add contracts to custom actions for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  10. Add Function configuration – Genesys Cloud Resource Centerhelp.genesys.cloud
  11. Call Data action overview – Genesys Cloud Resource Centerhelp.genesys.cloud
  12. Concepts for the data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  13. Credential types for the web services data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  14. Custom action fails for unexpected reason – Genesys Cloud Resource Centerhelp.genesys.cloud
  15. Data action fails during testing – Genesys Cloud Resource Centerhelp.genesys.cloud
  16. Edit, copy, export, or delete a data action for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  17. Encrypt Data action – Genesys Cloud Resource Centerhelp.genesys.cloud
  18. Get Secured Data action – Genesys Cloud Resource Centerhelp.genesys.cloud
  19. How the data actions integration works – Genesys Cloud Resource Centerhelp.genesys.cloud
  20. How to use the User Defined credential type – Genesys Cloud Resource Centerhelp.genesys.cloud
  21. How to use the User Defined (OAuth) credential type – Genesys Cloud Resource Centerhelp.genesys.cloud
  22. Import or export a data action for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  23. Look up data from an external source in scripts – Genesys Cloud Resource Centerhelp.genesys.cloud
  24. MTLS support for data actions – Genesys Cloud Resource Centerhelp.genesys.cloud
  25. Phone number searches with the data action integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  26. Release notes for the web services data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  27. Request configuration for data actions – Genesys Cloud Resource Centerhelp.genesys.cloud
  28. Requirements for the data actions integration – Genesys Cloud Resource Centerhelp.genesys.cloud
  29. Response configuration for data actions – Genesys Cloud Resource Centerhelp.genesys.cloud
  30. Test data actions for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  31. Use data actions for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  32. Use data actions in Architect for integrations – Genesys Cloud Resource Centerhelp.genesys.cloud
  33. Velocity macros for data actions – Genesys Cloud Resource Centerhelp.genesys.cloud
  34. Do data actions support mutual authentication of certificates? – Genesys Cloud Resource Centerhelp.genesys.cloud
  35. How many seconds before a data action times out? – Genesys Cloud Resource Centerhelp.genesys.cloud
  36. August 9, 2017 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  37. December 13, 2017 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  38. December 20, 2023 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  39. January 20, 2025 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  40. November 15, 2017 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  41. November 16, 2022 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  42. October 18, 2017 release notes – Genesys Cloud Resource Centerhelp.genesys.cloud
  43. Design Architect flow data actions for resiliency – Genesys Cloud Developer Centerdeveloper.genesys.cloud
  44. Limits (Data Actions) – Genesys Cloud Developer Centerdeveloper.genesys.cloud
  45. Genesys Cloud Platform API v2 definition (permission requirements per operation) – Genesysapi.mypurecloud.com
  46. Genesys Cloud CX summarised plan comparison – Genesyslibrary.genesys.com

Last reviewed

We work by introduction

Clients, partners and people introduced to us can reach the right specialist directly.

Who to contact