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.

Parameters

NameTypeDescription
session_idstringThe conversation’s session ID.
reasonstringWhy it went to the team, in the site’s language, for example that the visitor asked to talk to a person.
transcriptstringThe conversation as plain text, card numbers and IBANs masked; emails and phone numbers stay.
ticketarrayWhere 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.

  • 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.

What are your feelings