Hooks vs. Actions / Execute Code
Hooks let you use custom code with your bot, just like Actions and Execute Code Cards. The key difference is when the code runs:- Actions and Execute Code Cards run at some point in your Workflow.
- Hooks run during specific stages of the bot’s operation cycle
Overview
When you add a new Hook, it defines a function that executes every time your bot reaches a certain cycle of its operation. All Hooks take anevent parameter, which contains information about the event that triggered the Hook.
Some Hook types take additional parameters—check out the Hook guides on this page for more information.
Add a Hook
- Navigate to the Hooks section in the Studio’s left navigation bar.
- Select Create Hook, then choose a type for the Hook.
- 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 incomingevent.
Parameters:
Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
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:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
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:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
The user ID associated with this event.
The message sent by the bot
Before LLMz Execution
This Hook type executes its code before the LLMz engine begins its execution. Parameters:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
The user ID associated with this event.
The current context provided to the LLMz
Show child attributes
Show child attributes
The unique identifier of the LLMz execution, prefixed with
llmz_The version of the LLMz engine or context
Optional instructions provided to guide the LLMz execution
A list of objects relevant to the LLMz context
A list of tools available for the LLMz engine to use
The current loop count of the LLMz iteration process
The temperature setting used for the LLM model
The name or identifier of the LLM model being used.
The conversation transcript, including all prior messages in the current context
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:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
The user ID associated with this event.
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:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
The user ID associated with this event.
The result of the iteration
After Conversation End
This Hook type executes after the conversation has explicitly ended (transitioned to an End Node) Parameters:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
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 for your bot. Parameters:Information about the last incoming event in your bot’s execution.
Show child attributes
Show child attributes
The ID of the bot that experienced the event.
The ID of the conversation that the event took place in.
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.
The unique identifier for the event.
The integration that the event occurred on.
Information about Knowledge Bases queried for the event.
Show child attributes
Show child attributes
Array of Knowledge Bases queried for the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
Array of Knowledge Base results consulted for this event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The unique identifier for the current event’s message.
The payload for the current event.
A representation of the event in plain text. If the event is text message, this property will contain the message itself.
Data related to the state of the event.
Since most of this object’s properties are for internal use by Botpress, we’ve omitted its deeper structure from this documentation.
The Trigger that sent the event.
Show child attributes
Show child attributes
The ID of the conversation associated with this Trigger.
The name of the event that the Trigger sent.
The ID of the Workflow containing the Trigger.
The integration associated with the Trigger.
The ID of the Node that contains the Trigger.
The ID of the user associated with this Trigger.
The type of the event.
The user ID associated with this event.
The turn’s metadata
Show child attributes
Show child attributes
The token information and cost for the current turn
Show child attributes
Show child attributes
A summary of the token usage for the last turn
A detailed breakdown of token usage for the last turn
The number of billed tokens during the last turn
An array of token usages
Show child attributes
Show child attributes
The number of tokens in the usage
The AI spend for the usage (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000.
The duration (in milliseconds) of the usage
The location in the Workflow where the usage occurred
Whether the usage was cached
The total number of tokens used in the last turn
The total number of billed tokens used in the last turn
The AI spend for the last turn (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000.
The percentage of savings on AI spend for this turn.