---
name: kimaai_chatbot_quick_actions
type: filter
since: 1.4.0
tier: premium
feature: quick-actions
area: chatbot
summary: Changes the quick actions the chatbot offers at the start of a conversation and below each answer.
parameters:
  - name: actions
    type: array
    description: The quick actions of the settings for this place, each with id, label, type and payload.
  - name: context
    type: array
    description: placement (start or after_message), sessionId, postId, messageId, message (the answer's text) and messages (the conversation).
returns:
  type: array
  description: The quick actions to offer here.
---

# kimaai_chatbot_quick_actions

## When it fires

When the widget loads a conversation (`GET /wp-json/kimaai/v1/chatbot/history`), which it does when it opens and after every answer: once with `placement` `start` when the conversation has no messages yet, and once per answer of the chatbot with `placement` `after_message`. The attention popover beside the launcher loads the start actions the same way. `$actions` holds the quick actions of the settings for that place; below an answer those without keywords and those whose keywords the answer contains. Return them changed, add your own, or return an empty array to offer none.

An action is an array with `id`, `label`, `type` and `payload`, and the type decides the payload:

- `message`: sends `payload.message` as the visitor's message.
- `prefill`: puts `payload.text` into the message field.
- `link`: opens `payload.url`.
- `command`: runs a tool (`payload.mode` `force_tool` with `payload.tool`) or a callback (`payload.mode` `callback` with `payload.name` and `payload.args`), with `payload.message` as the visitor's message.

The history request carries no page, so `postId` is 0 there. Actions you return are sent as they are, so give each a unique `id` and a `label` the visitor can read.

## Example

```php
add_filter(
  'kimaai_chatbot_quick_actions',
  function (array $actions, array $context): array {
    // Below an answer about delivery, a link to the shipping page.
    if ($context['placement'] === 'after_message' && stripos((string) $context['message'], 'delivery') !== false) {
      $actions[] = [
        'id' => 'shipping',
        'label' => 'Shipping details',
        'type' => 'link',
        'payload' => ['url' => home_url('/shipping/')],
      ];
    }

    return $actions;
  },
  10,
  2
);
```

## Related

- `kimaai_chatbot_final_message`: changes the answer the actions follow.
