Data requests

Integrate custom APIs for injecting real-time data or actions in conversation

What's a Data request?

Data requests are custom integrations that send and retrieve data from tools in your tech stack. They can be used in two ways:

In a flow: Trigger an API call during a conversation using a Data Request node, then inject the returned data into subsequent nodes to keep responses dynamic and real time.

As an agentic tool: Attach as a Custom data request to your Generative Journey, allowing your agent to call the integration autonomously when completing user tasks.

Common use cases include:

• Providing available appointment times

• Authenticating a user and retrieving their profile or account data

• Offering real-time status updates

• Sending confirmation messages or emails

To access, click Resources in your workspace menu and choose Data requests:

Requirements

• Complete the Data request's implementation

• Set up the Response model schema. Optionally set up the Request model for payloads

• Trigger via a Data request node or Agentic Generative Journey® node in a flow

If invoked using a Data request node in your flow, information from your data source can then be relayed in messaging or used in conditional logic in subsequent nodes of the flow.

Implementation

Implementation is where you'll set up a static response or external integration for your Data request. When a data request is called via the data request node or agent tool in a Generative Journey node, it triggers the static response or HTTP method for engaging with your data.

Static mode

Choose to define a fixed JSON response. Ideal for prototypes or quick testing. Simply enter the response and click Save

External mode

Choose to integrate with an endpoint. Set the HTTP method, enter URL + optional custom headers. Use the CloudFormation template in the Instructions section and click Save

For external implementations, enabling the Dynamic toggle lets you edit header values directly from the Data request node’s side panel when the Data request is triggered in a flow.

If you’re working with sensitive data or reusing the same endpoint frequently, store it as a Secret in your workspace for added security and easier maintenance

Production and Development environments

Data requests can be configured with two different endpoints to allow for better flexibility and control during testing and development of your applications. Either setup allows you to change the URL, URL parameters, and Headers for each:

• Production: The endpoint called in deployed applications when a Data request node is hit during conversation where this request is assigned

• Development: Optional endpoint that can be called when testing conversations or flows in NLX

To swap from Production to Development environment while testing in your NLX workspace, select the settings gear from your Test widget and choose Development in the Environment dropdown.

API spec

HTTP payloads that are delivered to your Data request's configured URL endpoint contain several headers, including:

Header	Value	Description
Content-Type	application/json	The only content type currently supported is JSON
nlx-webhook-version	v3	The version associated with the data request configuration
x-nlx-botId	<uuid>	A unique identifier of an application
x-nlx-channelId	<uuid>	A unique identifier of the channel associated with an application
x-nlx-channelType	string	A human friendly label indicating the channel type in use such as API, AmazonChime or Genesys
x-nlx-conversationId	<uuid>	A unique identifier of the conversation that triggered this data request
x-nlx-correlationId	<uuid>	A unique identifier that can be used for debugging
x-nlx-deploymentKey	<uuid>	A unique identifier of the deployment associated with the application
x-nlx-intentId	string	The intent ID from where the data request has triggered
x-nlx-languageCode	string	The application's language code used in the current conversation
x-nlx-userId	string	A user identifier such as a E.164 format phone number, UUID or other formats depending on the channel type.

The body of the request your API receives may contain the conversation context (nlx_context) if the send context option is enabled in the data request settings. It will always include the properties defined in the Data request's request model.

Name	Type	Description
nlx_context	object	The conversation context containing essential values such as the conversationId and any context variables that have been set up to this point in the conversation
nlx_context.botId	string	A unique identifier of the application
nlx_context.channelType	string	A human friendly label indicating the channel type in use such as API, AmazonChime or Genesys
nlx_context.channelId	string	A unique identifier of the channel associated with the application
nlx_context.conversationId	string	A unique identifier of the conversation that triggered this data request
nlx_context.languageCode	string	The application's language code used in the current conversation
nlx_context.<attributeName>	string, number or boolean	A set value of a custom context attribute. The attribute name can be an alphanumeric string with dashes and underscores
<propertyName>	any	One or more set values corresponding to the schema defined in the data request's request model

The response body of your Data request should include the properties defined by the response model. Optionally, it can include the context object:

Name	Type	Description
context	object	A map of key value pairs that you would like to be set as context attributes
context.<attributeName>	string, number or boolean	A set value of a custom context attribute. The attribute name can be an alphanumeric string with dashes and underscores
<propertyName>	any	One or more set values corresponding to the schema defined in the data request's response model

For example, the response body of a Data request may look like this:

{
    "Profile": {
        "FirstName": "Alice",
        "Preferences": ["window seat", "aisle seat"]
    }
}

Response / request models

Data requests can be customized to both send and receive data through structured schemas that shape how information moves between NLX and your external systems.

• Response model: Shape the response body returned from your external data source so that values can be relayed naturally in conversation. Common examples include retrieving a user’s profile details, providing appointment times, or returning confirmation messages

• Request model (optional): Define the payload to be sent with your API call. You can populate these fields dynamically within a flow to tailor requests in real time. For example, passing a user’s name or selected option to your webhook when confirming an appointment or sending a welcome email

Auto-generate schema

Quickly define your response schema by selecting Auto-generate, pasting a sample JSON payload, and clicking Save. NLX automatically builds the schema based on your provided structure. Request schema is not used in static mode

Manual schema

Choose to define your schema field by field. Use + Add field to create new properties and select their data types. Enter names, repeat as needed, and click Save. For request models, provide a description for each property field if using the data request as a tool in an agentic Generative Journey

Click the three-dots menu beside a field to open its Settings, then toggle Sensitive to prevent those values from appearing in conversation logs.

Data property types

Select icon beside name field to adjust the property type:

• String: A simple text value, such as a customer's name

• Number: An integer, such as a customer's age

• Boolean: A value consisting of true or false

• List: A list of values that can have other response types nested within

  • Use if wanting to provide the values to a user for selection when employing a User choice node in your flow. Either set your overall schema to List or set it to an Object with a nested List type of the properties you want to provide as choices (you will need to use the Loop node to process properties in a List schema when wanting to reference those values in messaging or in a User choice node of your flow)

• Object: A well-defined structure of multiple values, such as name, age, occupation. Use if wanting to reference the values in the payload of the Data request node

Test

Quickly confirm your data request is set up and configured properly by using the Test feature.

• Select Test option in upper right of resource's page

• Click Run test on panel

Toggle on Dynamic setting under applicable Headers to test Dynamic headers in your test.

Sample setup:

Request

 curl -X POST 
https://nbd1ntgf7l.execute-api.us-east-1.amazonaws.com/v2/webhook
 -H 'content-type: application/json' -d '{ "variables": [{ "variableId": "Profile", "payload": { "email": "
[email protected]
" } }] }'

Expected Response

{
  "resolvedVariables": [
    {
      "variableId": "Profile",
      "value": {
        "id": "1234",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]"
      }
    }
  ],
  "unresolvedVariables": [],
  "context": { "KEY1": "VALUE1", "KEY2": 1234 }
}

The sample endpoint should receive a POST request with a body that sends the variableId and payload attribute. The response returns the resolvedVariables attribute with variableId variable and value object that can be mapped

• Select Response model tab > Select the type of object returned. In the example, the value attribute returns an Object with attributes firstName, lastName, and id

• Select Request model tab > Add the payload field. In the example, the payload field is email

• Click the Implementation tab and switch to External mode > Add the URL for the endpoint in the URL field

• Add the necessary headers, if applicable. Some webhook endpoints need an API key. For the example, none is needed

• Click Save

• Click Run Test to test the endpoint

The response should look identical to your expected response, indicating a successful setup.

Data request settings

• Description: Provide context on the purpose of the API for an agent to understand when assigned as a tool in an agentic Generative Journey

• Sensitive: Prevent the values for the entire data request from appearing in conversation logs. Useful for concealing personally identifiable information (PII). Disabled by default

• Stream state modifications: Enable if referencing the Data request in a flow that has state modifications applied to it and uses a Lifecycle hook to stream the state mods to your data without obstructing processes of the NLU

• Send context: Provides context variables available in a conversation session at the time the webhook is called

• Enable advanced data model: On by default as it supports use of the schema auto-generation feature and additional data structure improvements