> ## Documentation Index > Fetch the complete documentation index at: https://botpress.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Hooks Hooks **execute custom JavaScript code** at specific cycles of your bot's operation. For example: * [Before each outgoing message](#before-outgoing) * [After each LLMz iteration](#after-llmz-iteration) * [At the end of each conversation](#after-conversation-end) You can use Hooks to intercept and modify messages, perform logging, integrate with external systems, and more. > [!TIP] > > ### Hooks vs. Actions / Execute Code > > Hooks let you use custom code with your bot, just like [Actions](https://botpress.com/docs/studio/concepts/actions.md) and [Execute Code Cards](https://botpress.com/docs/studio/concepts/cards/execute-code.md). The key difference is when the code runs: > > * Actions and Execute Code Cards run at some point in your [Workflow](https://botpress.com/docs/studio/concepts/workflows.md). > * Hooks run during specific stages of the bot’s operation cycle ## Overview When you add a new Hook, it defines a [function](https://www.w3schools.com/js/js_functions.asp) that executes every time your bot reaches a certain cycle of its operation. All Hooks take an `event` parameter, which contains information about the event that triggered the Hook. > [!NOTE] > > Some Hook types take additional parameters—check out the Hook guides on this page for more information. ### Add a Hook 1. Navigate to the Hooks section in the Studio's left navigation bar. 2. Select **Create Hook**, then choose a type for the Hook. 3. Choose a name for the Hook. Done! *** ## Hook types Here's a breakdown of each type of Hook: ### Before Incoming This Hook type executes its code before your bot processes an incoming `event`. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. ### After Incoming This Hook type executes its code after the incoming message has been processed, but before the bot has responded. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. ### Before Outgoing This Hook type executes its code before the bot's reply is sent to the user. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. **outgoingEvent** `IO.OutgoingEvent` The message sent by the bot ### Before LLMz Execution This Hook type executes its code before the LLMz engine begins its execution. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. **context** `LLMZ.CreateContext` The current context provided to the LLMz **id** `string` The unique identifier of the LLMz execution, prefixed with `llmz_` **version** `any` The version of the LLMz engine or context **instructions** `string` Optional instructions provided to guide the LLMz execution **objects** `LLMZ.Obj[]` A list of objects relevant to the LLMz context **tools** `LLMZ.Tool[]` A list of tools available for the LLMz engine to use **loop** `number` The current loop count of the LLMz iteration process **temperature** `number` The temperature setting used for the LLM model **model** `string` The name or identifier of the LLM model being used. **transcript** `OAI.Message[]` The conversation transcript, including all prior messages in the current context **location** `LLMZ.Location` The current location within the bot's logic ### After LLMz Execution This Hook type executes its code after the LLMz engine finishes its execution. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. **execution** `LLMZ.ExecutionResult` The result of the execution ### After LLMz iteration Depending on how demanding the task is, the LLMz may loop through multiple iterations before finishing its execution. This Hook type executes its code after each iteration. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. **iteration** `LLMZ.IterationResult` The result of the iteration ### After Conversation End This Hook type executes after the conversation has **explicitly ended** (transitioned to an [End Node](https://botpress.com/docs/studio/concepts/nodes/introduction.md#end-node)) **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. ### After Turn End This Hook type executes after a full turn has completed—meaning the bot has received user input, processed it, and responded. You can use a Hook of this type to [track AI spend and token cost](https://botpress.com/docs/studio/guides/how-to/track-ai-spend-in-table.md) for your bot. **Parameters**: **event** `IncomingEvent` Information about the last incoming event in your bot's execution. **botId** `string` *required* The ID of the bot that experienced the event. **conversationId** `string` The ID of the conversation that the event took place in. **createdOn** `Date` *required* The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format). **direction** `EventDirection` *required* The direction of the event, indicating whether the event was received by the bot or sent from the bot. Possible values: * `'incoming'`: The event originated from the user and was received by the bot. * `'outgoing'`: The event was generated by the bot and sent to the user. **id** `string` *required* The unique identifier for the event. **integration** `string` The [integration](https://botpress.com/docs/integrations/) that the event occurred on. **kb** `object` Information about [Knowledge Bases](https://botpress.com/docs/studio/concepts/knowledge-base/introduction.md) queried for the event. **included** `Studio.KnowledgeBase.KB[]` *required* Array of Knowledge Bases queried for the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **results** `Studio.KnowledgeBase.ContentResult[]` Array of Knowledge Base results consulted for this event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **messageId** `string` The unique identifier for the current event's message. **payload** `object` *required* The payload for the current event. **preview** `string` *required* A representation of the event in plain text. If the event is text message, this property will contain the message itself. **state** `EventState` *required* Data related to the state of the event. > [!WARNING] > > Since most of this object's properties are for internal use by Botpress, we've omitted its deeper structure from this documentation. **tags** `EventTags` Any tags associated with the current event. These can contain useful data related to the integration associated with the event. **conversation** `object` Tags for the conversation. **message** `object` Tags for the message. **user** `object` Tags for the user. **trigger** `DM.Trigger` The [Trigger](https://botpress.com/docs/studio/concepts/triggers.md) that sent the event. **conversationId** `string` The ID of the conversation associated with this Trigger. **eventName** `string` The name of the event that the Trigger sent. **flowId** `string` *required* The ID of the Workflow containing the Trigger. **integration** `string` The integration associated with the Trigger. **nodeId** `string` *required* The ID of the Node that contains the Trigger. **userId** `string` The ID of the user associated with this Trigger. **type** `string` *required* The type of the event. **userId** `string` The user ID associated with this event. **metadata** `IO.TurnMetadata` The turn's metadata **tokens** `IO.TokenReport` The token information and cost for the current turn **summary** `string` A summary of the token usage for the last turn **details** `string` A detailed breakdown of token usage for the last turn **billedTokens** `number` The number of billed tokens during the last turn **usages** `IO.TokenUsage[]` An array of token usages **count** `number` The number of tokens in the usage **spend** `number` The AI spend for the usage (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000. **duration** `number` The duration (in milliseconds) of the usage **location** `string` The location in the Workflow where the usage occurred **cached** `boolean` Whether the usage was cached **totalTokens** `number` The total number of tokens used in the last turn **billedTokens** `number` The total number of billed tokens used in the last turn **cost** `number` The AI spend for the last turn (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000. **savingsPercent** `number` The percentage of savings on AI spend for this turn. ## Troubleshooting If your Hook isn't behaving as expected, you can [check your bot's logs](https://botpress.com/docs/studio/concepts/debugger-logs-json.md) to diagnose any problems. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.