Data requests

Data requests are custom integrations that let agentic CX designer send data to, or retrieve data from, external systems during a conversation.

Use data requests when your conversational AI application needs real-time information or needs to trigger an action in another system. For example, a data request can retrieve appointment availability, look up a customer profile, check order status, or send a confirmation message.

Data requests can be used in two main ways:

To access data requests, select Resources from your workspace menu, then choose Data requests.

Use data requests to connect conversations to systems such as scheduling tools, ticketing systems, order systems, account databases, and messaging services.

Common examples include:

How data requests work

A data request defines how agentic CX designer communicates with an external system.

When a data request is triggered, agentic CX designer can:

For example, a scheduling flow may collect a user's preferred date, send it to an appointment API, receive available time slots, and present those options back to the user.

Creating a data request

Use a name and description that make the purpose easy for teammates to understand.

Examples:

Implementation types

The Implementation tab defines what happens when the data request is called.

The following table describes the four implementation types.

Use a Static implementation when you want the data request to return sample data without calling an external system.

Static responses are useful when:

For example, you might return a sample list of appointment times so you can build and test a scheduling flow before connecting to the real scheduling system.

Use an External implementation when the data request should call a real API or webhook.

When configuring an external implementation, define details such as:

External implementations can support separate Production and Development endpoint configurations. This lets you test safely against a development endpoint before using production systems.

If the endpoint requires authentication, use Secrets instead of hardcoding API keys, tokens, or credentials directly into headers or payloads.

Use an MCP implementation when the external service exposes one or more tools through an MCP server.

When configuring an MCP implementation, you provide the MCP endpoint details, such as:

After the MCP implementation is configured, use Sync to retrieve the available tools from the MCP server. Synced tools appear in the Tools section of the data request.

From the Tools section, you can:

Each tool can include a description and an argument schema that explains what information the tool expects.

MCP implementations can support separate Production and Development endpoint configurations. This lets you test safely against a development endpoint before using production systems.

If the endpoint requires authentication, use Secrets instead of hardcoding API keys, tokens, or credentials directly into headers or payloads.

For external or MCP implementations, dynamic headers can let you adjust header values when the data request is used.

Use dynamic headers when a header value may change based on the flow, environment, or context.

For sensitive or reusable values, such as API keys, bearer tokens, or authorization headers, use Secrets instead of entering the value directly.

Use a Connect flow module implementation when a data request should call a published flow module in your Connect Customer instance. A flow module packages conversation logic that you author, version, and govern in Connect Customer. With this implementation type, agentic CX designer invokes that logic during a conversation and returns its output to your application. You reuse governed logic instead of standing up and maintaining an external endpoint.

When you configure a Connect flow module implementation, you select and review the following items:

When you configure the implementation, you choose a module version. Choose Latest to always use the current published version of the module. When you republish the module, the data request uses the new current version. Choose a specific version number to pin the data request to that exact version. The data request keeps using that version even after you republish the module.

For a Connect flow module data request, the request and response models are read-only. These models derive from the module's input and output parameters, which you edit in Connect Customer. You cannot change the fields of these models in agentic CX designer. The only setting you can edit here is each field's sensitivity.

After you configure the implementation, add the data request to a flow so your conversation can call the module and use its results. This procedure adds a data request node that calls the module and makes the returned data available to later nodes.

Before you start, configure the Connect flow module implementation for the data request, including the module, version, and models. For instructions on preparing a module in Connect Customer, see Create module as tools.

The Payload editor is bound to the module's declared input schema. It marks required fields.

The following limits apply to a Connect flow module data request.

The module's response is limited to 1 MiB (1,048,576 bytes). If a response is larger than this limit, agentic CX designer rejects it instead of truncating it, and the data request takes the failure path. Because the limit is measured in bytes, a response that contains multi-byte characters reaches the limit with fewer characters.

Use a mock response that matches the shape of the module's response model so that your tests behave like a real invocation. The following JSON mock response returns an order status:

{
  "orderStatus": "SHIPPED",
  "estimatedDelivery": "2026-10-02",
  "carrier": "ExampleCarrier"
}

When you test the data request, agentic CX designer returns this response instead of invoking the module. To reference a field of this result downstream, use the output variable name. For example, if the output variable is named orderLookup, reference orderLookup.orderStatus.

In the Payload editor, map each required input field to a literal value or to conversation data. In the following example, replace A12345 and C67890 with your own order and customer identifiers.

The following JSON payload maps two values to the module's declared input fields:

{
  "orderId": "A12345",
  "customerId": "C67890"
}

Request model

The request model defines the optional payload that agentic CX designer sends to the external system.

Use a request model when the API needs values from the conversation.

You may select the Auto-generate option (star icon) to input sample JSON for easily constructing a complex schema structure.

Examples:

Fields in the request model can be populated dynamically from values captured in the conversation, such as slots, context variables, system variables, or prior data request results.

Response model

The response model defines the structure of the data returned from the external system.

Use the response model to shape returned data so it can be referenced in the conversation.

You may select the Auto-generate option (star icon) to input sample JSON for easily constructing a complex schema structure.

Examples:

A clear response model makes it easier to use returned values in later nodes, prompts, user choices, conditions, and messages.

When defining request and response models, choose the property type that matches the value.

Use Array when the response returns multiple values that may need to be presented as options. Use Object when the response returns a structured item with multiple properties.

List responses are useful when a user needs to choose from returned options.

Examples:

A list can be used with a User choice node when the user should select from returned options.

If the response contains a list of objects, use a Loop node to iterate over the nested values, or a Transform node or Generative text node to change the schema to a desired output and reference the correct nested properties depending on how you want to display or process the returned values.

Sensitive fields

You can mark fields as Sensitive to help prevent values from appearing in conversation logs where supported.

Use sensitive fields for values such as:

To mark a field as sensitive, open the field settings and enable the Sensitive toggle.

You may also use the data request-level sensitive setting if the entire data request should be treated as sensitive.

Data request settings

Testing a data request

Use the test feature to confirm that a data request is configured correctly before using it in a flow or agent node.

A successful test should return the expected response structure based on your response model.

If the test fails, review:

Using a data request in a flow

After the data request returns successfully, use the returned values in downstream messages, conditions, user choices, or other nodes.

Example:

"I found three available times: {AvailableTimes}. Which one works best for you?"

Using a data request as an agent tool

Use this pattern when the agent should decide when to call the integration as part of completing a task.

Example:

A rescheduling agent may collect the user's preferred date, call a data request to retrieve availability, ask the user to choose a time, then call another data request to update the appointment.

Synchronous and asynchronous data requests

On the data request node, the Mode control sets whether the conversation waits for the data request to finish. Mode has two options: Synchronous and Asynchronous. This setting is available on voice and chat.

In Synchronous mode, the conversation turn waits for the data request to resolve before it continues. The node routes the conversation on its result. For example, it can route along a success, failure, or timeout path.

In Asynchronous mode, the data request runs on a background path and the conversation turn continues without waiting. The result becomes available on a later turn.

Asynchronous mode removes the success and failure edges from the node. Because there is no failure edge in asynchronous mode, you must design failure handling differently. Plan how a later turn reads the result, and how the conversation responds when the result is missing or indicates a failure.

You can add an In progress edge to deliver a message while the request is still resolving. When you use the In progress edge, set a Wait time from 0 to 30,000 milliseconds. The conversation follows the In progress edge to deliver your message, then returns to the data request.

Resolve flow module data request errors

Use the following table to resolve the messages you might see when you configure a Connect flow module data request in agentic CX designer, or when a data request fails during a conversation. Some messages appear in the designer while you build. Others reach you as the failure reason on a data request that failed during a live conversation. The symptom column shows the message text where a message exists. The cause and remediation help you correct the underlying configuration.

Best practices