---
name: kimaai_chatbot_instructions
type: filter
since: 1.2.5
tier: free
feature: chatbot
area: chatbot
summary: Changes the chatbot's instructions for one request, for example by the page the visitor is on.
parameters:
  - name: instructions
    type: string
    description: The instructions of the chatbot settings.
  - name: chatbot_settings
    type: array
    description: The chatbot settings.
  - name: post_id
    type: int
    description: The ID of the page the visitor is on, or 0.
  - name: post_section
    type: string
    description: The id of the heading the visitor is reading, or empty.
returns:
  type: string
  description: The instructions to send.
surfaces: [chatbot, search]
---

# kimaai_chatbot_instructions

## When it fires

Each time a chatbot request or a search answer builds the messages for the provider, before the chat history and the visitor's message are added; the admin assistant has `kimaai_admin_assistant_instructions` instead. `$post_id` is the page the chat sits on, and 0 in a search answer.

KimaAI hooks it itself at priority 10 for the content awareness, which fills `{post_url}`, `{post_title}`, `{post_content}` and `{post_section}` with the current page (and empties them when awareness is off), and the WooCommerce integration (Pro) adds its own lines. After the filter KimaAI fills `{current_date}` and `{glossary}`, so placeholders your callback adds are filled too. The instructions are the first system message; in a search answer the search results follow in a system message of their own.

## Example

```php
add_filter(
  'kimaai_chatbot_instructions',
  function (string $instructions, array $chatbot_settings, int $post_id): string {
    if ($post_id && get_post_type($post_id) === 'product') {
      $instructions .= "\nThe visitor is looking at a product: mention the delivery time when they ask about orders.";
    }

    return $instructions;
  },
  10,
  3
);
```

## Related

- `kimaai_chatbot_content_awareness_post_types`: which pages the content awareness may describe.
- `kimaai_chatbot_ai_payload`: changes the rest of the request.
- `kimaai_admin_assistant_instructions`: the admin assistant's instructions.
