Implementation

Easily set up your Lifecycle hook's external webhook in your NLX workspace

What's the Implementation of a lifecycle hook?

A Lifecycle hook's Implementation is where you'll set up a static response or external webhook/API URL for your Lifecycle hook. When a conversation with your conversational AI application starts, ends, escalates, or streams state modifications and a Lifecycle hook is attached at one of those stages, the webhook will trigger the specified URL and run the process required.

Need more context? See Application lifecycle

Implementation tab of a lifecycle hook

---

External implementation

External mode is used for integrating with a URL that triggers your Lifecycle hook:

• Set implementation toggle to External

• Enter the URL

• Use NLX's AWS CloudFormation template provided within the Instructions section

• Click Save

Whether you have sensitive data or frequently enter the same URL string, try setting up a Secret in your workspace for enhanced security and efficiency.

Optional setup

• Headers: expand section > Click + Add header > Enter the Name and Value to be sent with the request. Useful for custom headers such as an API key, content type, content length, etc.

Now that your implementation setup is complete, attach your Lifecycle hook to an application under the application's Lifecycle tab.

---

Static response

Static mode is useful for creating a static response when building demos or for early testing.

• Set implementation toggle to Static

• Enter your response in JSON structure

• Click Save

Now that your implementation setup is complete, attach yourLifecycle hook to an application under the application's Lifecycle tab.

---

API spec

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 appplication	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

For example, the response body of a Lifecycle hook for a conversationStart event type may look like this:

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

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