> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-pb-update-api.mintlify.site/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](/studio/concepts/actions) and [Execute Code Cards](/studio/concepts/cards/execute-code). The key difference is when the code runs:

  * Actions and Execute Code Cards run at some point in your [Workflow](/studio/concepts/workflows).
  * Hooks run during specific stages of the bot’s operation cycle
</Tip>

## 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.
</Note>

### Add a Hook

1. Navigate to the <Icon icon="anchor" /> 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**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

### After Incoming

This Hook type executes its code after the incoming message has been processed, but before the bot has responded.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

### Before Outgoing

This Hook type executes its code before the bot's reply is sent to the user.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="outgoingEvent" type="IO.OutgoingEvent">
  The message sent by the bot
</ResponseField>

### Before LLMz Execution

This Hook type executes its code before the LLMz engine begins its execution.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="context" type="LLMZ.CreateContext">
  The current context provided to the LLMz

  <Expandable>
    <ResponseField name="id" type="string">
      The unique identifier of the LLMz execution, prefixed with `llmz_`
    </ResponseField>

    <ResponseField name="version" type="any">
      The version of the LLMz engine or context
    </ResponseField>

    <ResponseField name="instructions" type="string" optional>
      Optional instructions provided to guide the LLMz execution
    </ResponseField>

    <ResponseField name="objects" type="LLMZ.Obj[]">
      A list of objects relevant to the LLMz context
    </ResponseField>

    <ResponseField name="tools" type="LLMZ.Tool[]">
      A list of tools available for the LLMz engine to use
    </ResponseField>

    <ResponseField name="loop" type="number">
      The current loop count of the LLMz iteration process
    </ResponseField>

    <ResponseField name="temperature" type="number">
      The temperature setting used for the LLM model
    </ResponseField>

    <ResponseField name="model" type="string">
      The name or identifier of the LLM model being used.
    </ResponseField>

    <ResponseField name="transcript" type="OAI.Message[]">
      The conversation transcript, including all prior messages in the current context
    </ResponseField>

    <ResponseField name="location" type="LLMZ.Location">
      The current location within the bot's logic
    </ResponseField>
  </Expandable>
</ResponseField>

### After LLMz Execution

This Hook type executes its code after the LLMz engine finishes its execution.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="execution" type="LLMZ.ExecutionResult">
  The result of the execution
</ResponseField>

### 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**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="iteration" type="LLMZ.IterationResult">
  The result of the iteration
</ResponseField>

### After Conversation End

This Hook type executes after the conversation has **explicitly ended** (transitioned to an [End Node](/studio/concepts/nodes/introduction#end-node))

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

### 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](/studio/guides/how-to/track-ai-spend-in-table/) for your bot.

**Parameters**:

<ResponseField name="event" type="IncomingEvent">
  Information about the last incoming event in your bot's execution.

  <Expandable>
    <ResponseField name="botId" type="string" required>
      The ID of the bot that experienced the event.
    </ResponseField>

    <ResponseField name="conversationId" type="string">
      The ID of the conversation that the event took place in.
    </ResponseField>

    <ResponseField name="createdOn" type="Date" required>
      The data and time when the event was created (in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format).
    </ResponseField>

    <ResponseField name="direction" type="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.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      The unique identifier for the event.
    </ResponseField>

    <ResponseField name="integration" type="string">
      The [integration](/integrations/) that the event occurred on.
    </ResponseField>

    <ResponseField name="kb" type="object">
      Information about [Knowledge Bases](/studio/concepts/knowledge-base/introduction) queried for the event.

      <Expandable>
        <ResponseField name="included" type="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.
          </Warning>
        </ResponseField>

        <ResponseField name="results" type="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.
          </Warning>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageId" type="string">
      The unique identifier for the current event's message.
    </ResponseField>

    <ResponseField name="payload" type="object" required>
      The payload for the current event.
    </ResponseField>

    <ResponseField name="preview" type="string" required>
      A representation of the event in plain text. If the event is text message, this property will contain the message itself.
    </ResponseField>

    <ResponseField name="state" type="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.
      </Warning>
    </ResponseField>

    <ResponseField name="tags" type="EventTags">
      Any tags associated with the current event. These can contain useful data related to the integration associated with the event.

      <Expandable>
        <ResponseField name="conversation" type="object">
          Tags for the conversation.
        </ResponseField>

        <ResponseField name="message" type="object">
          Tags for the message.
        </ResponseField>

        <ResponseField name="user" type="object">
          Tags for the user.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trigger" type="DM.Trigger">
      The [Trigger](/studio/concepts/triggers) that sent the event.

      <Expandable>
        <ResponseField name="conversationId" type="string">
          The ID of the conversation associated with this Trigger.
        </ResponseField>

        <ResponseField name="eventName" type="string">
          The name of the event that the Trigger sent.
        </ResponseField>

        <ResponseField name="flowId" type="string" required>
          The ID of the Workflow containing the Trigger.
        </ResponseField>

        <ResponseField name="integration" type="string">
          The integration associated with the Trigger.
        </ResponseField>

        <ResponseField name="nodeId" type="string" required>
          The ID of the Node that contains the Trigger.
        </ResponseField>

        <ResponseField name="userId" type="string">
          The ID of the user associated with this Trigger.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="type" type="string" required>
      The type of the event.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The user ID associated with this event.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="IO.TurnMetadata">
  The turn's metadata

  <Expandable>
    <ResponseField name="tokens" type="IO.TokenReport">
      The token information and cost for the current turn

      <Expandable>
        <ResponseField name="summary" type="string">
          A summary of the token usage for the last turn
        </ResponseField>

        <ResponseField name="details" type="string">
          A detailed breakdown of token usage for the last turn
        </ResponseField>

        <ResponseField name="billedTokens" type="number">
          The number of billed tokens during the last turn
        </ResponseField>

        <ResponseField name="usages" type="IO.TokenUsage[]">
          An array of token usages

          <Expandable>
            <ResponseField name="count" type="number">
              The number of tokens in the usage
            </ResponseField>

            <ResponseField name="spend" type="number">
              The AI spend for the usage (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000.
            </ResponseField>

            <ResponseField name="duration" type="number">
              The duration (in milliseconds) of the usage
            </ResponseField>

            <ResponseField name="location" type="string">
              The location in the Workflow where the usage occurred
            </ResponseField>

            <ResponseField name="cached" type="boolean">
              Whether the usage was cached
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="totalTokens" type="number">
          The total number of tokens used in the last turn
        </ResponseField>

        <ResponseField name="billedTokens" type="number">
          The total number of billed tokens used in the last turn
        </ResponseField>

        <ResponseField name="cost" type="number">
          The AI spend for the last turn (in nanodollars). To get the number in dollars, divide this number by 1,000,000,000.
        </ResponseField>

        <ResponseField name="savingsPercent" type="number">
          The percentage of savings on AI spend for this turn.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Troubleshooting

If your Hook isn't behaving as expected, you can [check your bot's logs](/studio/concepts/debugger-logs-json) to diagnose any problems.