# Custom integrations ## 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: 1. Trigger an API call during a conversation using a [*Data request* node](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#data-request), then inject the returned data into subsequent nodes to keep responses dynamic and real time 2. As an agentic tool: Attach as a *Custom data request* to your [Generative Journey](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#agentic-mode), 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*: {% @arcade/embed flowId="wBoUCToKf6IclJz25bh0" url="" %} ### 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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#data-request) or [Agentic Generative Journey® node](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#agentic-mode) in a flow {% hint style="info" %} 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. {% endhint %} ### 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. {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} If you’re working with sensitive data or reusing the same endpoint frequently, [store it as a *Secret*](https://docs.nlx.ai/platform/nlx-platform-guide/building/secrets) in your workspace for added security and easier maintenance {% endhint %} {% @arcade/embed flowId="0dWwlkvd8TQNjmsvLJIU" url="" %} #### 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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#data-request) is hit during conversation where this request is assigned * *Development*: Optional endpoint that can be called when [testing conversations or flows](/platform/nlx-platform-guide/ai-applications/testing.md) 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 {% hint style="info" %} Click the three-dots menu beside a field to open its *Settings*, then toggle *Sensitive* to prevent those values from appearing in conversation logs. {% endhint %} {% @arcade/embed flowId="oPLfbAHdlx3fx0lxGLKS" url="" %} #### 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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#user-choice) 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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#loop) 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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#data-request) ### Test Quickly confirm your data request is set up and configured properly by using the *Test* feature. {% @arcade/embed flowId="ZIjwkiAZazdp7tvi9q9j" url="" %} * Select *Test* option in upper right of resource's page * Click *Run test* on panel {% hint style="info" %} Toggle on Dynamic setting under applicable Headers to test Dynamic headers in your test. {% endhint %} Sample setup: {% tabs %} {% tab title="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": " jdoe@example.com " } }] }' ``` {% endtab %} {% tab title="Expected Response" %} ``` { "resolvedVariables": [ { "variableId": "Profile", "value": { "id": "1234", "firstName": "John", "lastName": "Doe", "email": "jdoe@example.com" } } ], "unresolvedVariables": [], "context": { "KEY1": "VALUE1", "KEY2": 1234 } } ``` {% endtab %} {% endtabs %} 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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#agentic-mode)
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](/platform/nlx-platform-guide/flows-and-building-blocks/overview/nodes.md#state-modifications) applied to it and uses a [Lifecycle hook](/platform/nlx-platform-guide/flows-and-building-blocks/advanced/lifecycle-hooks.md) to stream the state mods to your data without obstructing processes of the NLU
Send context Provides [context variables](/platform/nlx-platform-guide/flows-and-building-blocks/advanced/context-variables.md) 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
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.nlx.ai/platform/nlx-platform-guide/integrations/types/data-requests.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.