---
name: kimaai_chatbot_handoff
type: action
since: 1.5.4
tier: premium
feature: human-handoff
area: chatbot
summary: Fires when a conversation went to the team, with the ticket or reference it got.
parameters:
  - name: session_id
    type: string
    description: The conversation's session ID.
  - name: reason
    type: string
    description: Why it went to the team, in the site's language, for example that the visitor asked to talk to a person.
  - name: transcript
    type: string
    description: The conversation as plain text, card numbers and IBANs masked; emails and phone numbers stay.
  - name: ticket
    type: array
    description: Where it went, as the visitor's ticket card shows it; channel, reference and url.
surfaces: [chatbot]
---

# kimaai_chatbot_handoff

## When it fires

When the human handoff (Pro) delivered a conversation to the team, once per conversation. The triggers are the handoff settings: repeated negative ratings in one conversation, an answer that failed the groundedness check, or the visitor asking for a person. It fires after the delivery succeeded and the conversation was marked as handed over, so a failed delivery, which KimaAI tries again on the next trigger, does not fire it.

`$ticket` says where the conversation went:

- `channel`: the helpdesk's key (`zendesk`, `freshdesk`, `helpscout` or `fluentsupport`) when a ticket was opened for a logged-in visitor, else `email`, which also covers the webhook of the settings.
- `reference`: what the visitor sees, `#123` for a helpdesk ticket or a reference such as `KA-1A2B3C4D` for an email handoff.
- `url`: a page where the customer can follow the ticket; empty with the helpdesks KimaAI connects today.

`$ticket` came after 1.5.13; callbacks written for three parameters keep working. Evaluation conversations (`wp kimaai eval`) never go to the team and never fire it.

## Example

```php
add_action(
  'kimaai_chatbot_handoff',
  function (string $session_id, string $reason, string $transcript, array $ticket): void {
    $text = sprintf('A chat went to the team (%s): %s %s', $reason, $ticket['channel'], $ticket['reference']);

    wp_remote_post(
      'https://hooks.slack.com/services/T000/B000/XXXX',
      [
        'headers' => ['Content-Type' => 'application/json'],
        'body' => wp_json_encode(['text' => trim($text . ' ' . $ticket['url'])]),
      ]
    );
  },
  10,
  4
);
```

Replace the Slack address with your incoming webhook. The transcript stays out of the message: it can hold the visitor's email address or phone number.

## Related

- `kimaai_chatbot_message_feedback_saved`: the negative ratings that can trigger a handoff.
- `kimaai_chatbot_ungrounded_answer`: the failed groundedness check that can trigger one.
