# Lifecycle hooks

{% hint style="info" %}
This feature is currently available to enterprise tiers only.
{% endhint %}

### **What's a Lifecycle hook?**

Lifecycle hooks let you send or receive data or trigger an event at key stages of a conversation session. They’re useful for passing information between NLX and external systems or for setting context variables when a session begins. Unlike *Data requests* or *Actions* that operate within flows, *Lifecycle hooks* are attached at the application level. They execute automatically at defined points in the conversation lifecycle:

* *Conversation start*: Initialize data or set context variables
* *Conversation escalation*: Send or receive data during a handoff
* *Conversation end*: Finalize data or trigger follow-up actions
* *Stream state modifications*: Transmit updates from *Data requests* in real time

To access, click *Resources* in your workspace menu and choose *Lifecycle hooks*:

{% @arcade/embed flowId="vZ8TjdJrntwFtlfO6TEz" url="<https://app.arcade.software/share/vZ8TjdJrntwFtlfO6TEz>" %}

## Requirements

* [ ] Complete the *Lifecycle hook*'s implementation
* [ ] Attach it to one or more [*Lifecycles* on a custom application](https://docs.nlx.ai/platform/nlx-platform-guide/ai-applications/setup#custom-app-settings)

## Implementation

The *Implementation* section defines how your lifecycle hook runs. Depending on the lifecycle stage you’ll configure in your custom application, it will either send a request to an external webhook or return a static JSON response when triggered.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><i class="fa-infinity">:infinity:</i></td><td><strong>Static mode</strong></td><td>Choose to define a fixed JSON response. Ideal for prototypes or quick testing. Simply enter the response and click <em>Save</em></td></tr><tr><td><i class="fa-plug">:plug:</i></td><td><strong>External mode</strong></td><td>Choose to integrate with an endpoint. Enter URL + optional custom headers. Use the CloudFormation template in the <em>Instructions</em> section and click <em>Save</em></td></tr></tbody></table>

{% 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/flows-and-building-blocks/advanced/secrets) in your workspace for added security and easier maintenance
{% endhint %}

{% @arcade/embed flowId="SIhlDZaxxhrqzqR9HIfH" url="<https://app.arcade.software/share/SIhlDZaxxhrqzqR9HIfH>" %}

<details>

<summary><strong>API spec</strong></summary>

{% hint style="warning" %}
Lifecycle hooks have a response timeout set to 3 seconds. Currently this value cannot be adjusted.
{% endhint %}

HTTP POST payloads that are delivered to your *Lifecycle hook*'s configured URL endpoint contain a few headers, including:

<table><thead><tr><th width="308">Header</th><th width="110">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td>application/json</td><td>The only content type currently supported is JSON</td></tr><tr><td><code>nlx-correlation-id</code></td><td>&#x3C;uuid></td><td>A unique identifier that can be used for debugging</td></tr><tr><td><code>nlx-lifecycle-hook-version</code></td><td>v1</td><td>The version associated with the Lifecycle hook configuration</td></tr></tbody></table>

The body of the POST request your webhook will receive may contain:

<table><thead><tr><th width="224">Name</th><th width="92">Type</th><th width="257">Description</th><th>Event Type</th></tr></thead><tbody><tr><td><code>eventType</code></td><td>string</td><td>The event type determined by the application's<a href="../../../ai-applications/setup#custom-app-settings"> Lifecycle</a> configuration. Possible values: <code>conversationStart</code>, <code>conversationEnd</code>, <code>escalation</code>, <code>messageReceived</code>, <code>stateModification</code></td><td>All</td></tr><tr><td><code>context</code></td><td>object</td><td>The conversation context containing essential values such as the <code>conversationId</code> and any <a href="../context-variables#use-a-context-variable">context variables</a> that have been set up to this point in the conversation</td><td>All</td></tr><tr><td><code>context.botId</code></td><td>string</td><td>A unique identifier of the application associated with this Lifecycle hook that has been triggered</td><td>All</td></tr><tr><td><code>context.channelType</code></td><td>string</td><td>A human friendly label indicating the channel type in use such as <code>API</code>, <code>AmazonChime</code> or <code>Genesys</code></td><td>All</td></tr><tr><td><code>context.channelId</code></td><td>string</td><td>A unique identifier of the channel associated with the application</td><td>All</td></tr><tr><td><code>context.conversationId</code></td><td>string</td><td>A unique identifier of the conversation that triggered this Lifecycle hook</td><td>All</td></tr><tr><td><code>context.languageCode</code></td><td>string</td><td>The application's <a href="../translations#supported-languages">language code </a>used in the current conversation</td><td>All</td></tr><tr><td><code>context.lastUtterance</code></td><td>string</td><td>The last user utterance captured before the Lifecycle hook has triggered</td><td>All, except <code>conversationStart</code> and <code>stateModification</code></td></tr><tr><td><code>context.intentId</code></td><td>string</td><td>The intent ID from where the Lifecycle hook has triggered </td><td>All, except <code>conversationStart</code> and <code>stateModification</code></td></tr><tr><td><code>context.userId</code></td><td>string</td><td>A user identifier such as a E.164 format phone number, UUID or other formats depending on the channel type</td><td>All</td></tr><tr><td><code>context.&#x3C;attributeName></code></td><td>any</td><td>A set value of a custom context variable</td><td>All</td></tr><tr><td><code>context.request</code></td><td>object</td><td>The request message information</td><td><code>messageReceived</code></td></tr><tr><td><code>context.request.text</code></td><td>string</td><td>The user utterance</td><td><code>messageReceived</code></td></tr><tr><td><code>context.request.intentId</code></td><td>string</td><td>The intent ID if the request was structured, void of a user utterance</td><td><code>messageReceived</code></td></tr><tr><td><code>events</code></td><td>array of objects</td><td>An array of objects, where each item represents a state modification</td><td><code>stateModification</code></td></tr><tr><td><code>event.name</code></td><td>string</td><td>The name of the Data request property being modified, such as Profile.FirstName</td><td><code>stateModification</code></td></tr><tr><td><code>event.before</code></td><td>object</td><td>The whole Data request object before the state modifications</td><td><code>stateModification</code></td></tr><tr><td><code>event.after</code></td><td>object</td><td>The whole Data request object after the state modifications</td><td><code>stateModification</code></td></tr><tr><td><code>event.timestamp</code></td><td>string</td><td>The timestamp in milliseconds indicating when the state modification happened</td><td><code>stateModification</code></td></tr></tbody></table>

The response body of your Lifecycle hook can optionally include the following properties:

<table><thead><tr><th>Name</th><th width="171">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>context</code></td><td>object</td><td>A map of key value pairs that you would like to be set as context variables</td></tr><tr><td><code>context.&#x3C;attributeName></code></td><td>string, number or boolean</td><td>A set value of a custom context variable. The variable name can be an alphanumeric string with dashes and underscores</td></tr></tbody></table>

The response body of a *Lifecycle hook* for a `conversationStart` event type may look like this:

```json
{
    "context": {
        "FirstName": "Alice",
        "AccountNumber": 9932,
        "Subscribed": true
    }
}
```

</details>


---

# 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/flows-and-building-blocks/advanced/lifecycle-hooks.md?ask=<question>
```

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.