Lifecycle hooks

Trigger general actions at the start, end, or escalation point of your conversations

This feature is currently available to enterprise tiers only.

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:

Requirements

• Complete the Lifecycle hook's implementation

• Attach it to one or more Lifecycles on a custom application

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.

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. Enter URL + optional custom headers. Use the CloudFormation template in the Instructions section and click Save

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

API spec

Lifecycle hooks have a response timeout set to 3 seconds. Currently this value cannot be adjusted.

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

Header	Value	Description
Content-Type	application/json	The only content type currently supported is JSON
nlx-correlation-id	<uuid>	A unique identifier that can be used for debugging
nlx-lifecycle-hook-version	v1	The version associated with the Lifecycle hook configuration

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

Name	Type	Description	Event Type
eventType	string	The event type determined by the application's Lifecycle configuration. Possible values: conversationStart, conversationEnd, escalation, messageReceived, stateModification	All
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	All
context.botId	string	A unique identifier of the application associated with this Lifecycle hook that has been triggered	All
context.channelType	string	A human friendly label indicating the channel type in use such as API, AmazonChime or Genesys	All
context.channelId	string	A unique identifier of the channel associated with the application	All
context.conversationId	string	A unique identifier of the conversation that triggered this Lifecycle hook	All
context.languageCode	string	The application's language code used in the current conversation	All
context.lastUtterance	string	The last user utterance captured before the Lifecycle hook has triggered	All, except conversationStart and stateModification
context.intentId	string	The intent ID from where the Lifecycle hook has triggered	All, except conversationStart and stateModification
context.userId	string	A user identifier such as a E.164 format phone number, UUID or other formats depending on the channel type	All
context.<attributeName>	any	A set value of a custom context variable	All
context.request	object	The request message information	messageReceived
context.request.text	string	The user utterance	messageReceived
context.request.intentId	string	The intent ID if the request was structured, void of a user utterance	messageReceived
events	array of objects	An array of objects, where each item represents a state modification	stateModification
event.name	string	The name of the Data request property being modified, such as Profile.FirstName	stateModification
event.before	object	The whole Data request object before the state modifications	stateModification
event.after	object	The whole Data request object after the state modifications	stateModification
event.timestamp	string	The timestamp in milliseconds indicating when the state modification happened	stateModification

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

Name	Type	Description
context	object	A map of key value pairs that you would like to be set as context variables
context.<attributeName>	string, number or boolean	A set value of a custom context variable. The variable name can be an alphanumeric string with dashes and underscores

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

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