Implementation

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

What's the Implementation tab?

Implementation is where you'll set up a static response or external webhook/API URL for your lifecycle hook. When a conversation with a bot 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 Bot lifecycle & settings

---

Access

To access this feature, click the Implementation tab of your 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 parameter 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 a bot under the bot'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 your lifecycle hook to a bot under the bot's Lifecycle tab.

---

API spec

HTTP POST payloads that are delivered to your lifecycle hook's configured URL endpoint will 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 with the NLU Logs.
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 Bot 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 attributes that have been set up to this point in the conversation.	All
context.botId	string	A unique identifier of the bot associated with this lifecycle hook which 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 bot.	All
context.conversationId	string	A unique identifier of the conversation that triggered this lifecycle hook.	All
context.languageCode	string	The bot 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 attribute.	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 attributes.
context.<attributeName>	string, number or boolean	A set value of a custom context attribute. The attribute 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.