Custom integrations
Integrate custom APIs for injecting real-time data or actions in conversation
What's a custom integration?
Data requests are custom integrations that send and retrieve data from tools and services in your tech stack. They can be used in two ways:
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
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.
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.
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
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:
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
Last updated