# 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/types/core#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/types/core#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>