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,helpscoutorfluentsupport) when a ticket was opened for a logged-in visitor, elseemail, which also covers the webhook of the settings.reference: what the visitor sees,#123for a helpdesk ticket or a reference such asKA-1A2B3C4Dfor 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.
Parameters
| Name | Type | Description |
|---|---|---|
session_id | string | The conversation’s session ID. |
reason | string | Why it went to the team, in the site’s language, for example that the visitor asked to talk to a person. |
transcript | string | The conversation as plain text, card numbers and IBANs masked; emails and phone numbers stay. |
ticket | array | Where it went, as the visitor’s ticket card shows it; channel, reference and url. |
Example
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.