kimaai_chatbot_tool_call

When it fires

Once for each tool call the AI model makes in a chatbot answer, an admin assistant answer or a search answer, streamed or not. Before it, KimaAI refuses a tool the request did not offer (kimaai_chatbot_tools_registry) and asks kimaai_tool_call_allowed; a refused or blocked call never reaches this filter. After it, the result goes back to the model, which writes its answer from it or calls the next tool.

The filter starts with null. The callback that knows the tool returns its result; every other callback returns $result unchanged, also when it is not null. KimaAI’s own callbacks: at priority 5 the contact form tool of lead capture and, in Pro, the handoff, the meeting booking and the customer tools; at 10 the admin assistant’s settings tools and, in Pro, the tool router, which answers every tool it is asked about (the catalogue’s callbacks, the custom functions, or an error for an unknown name). So add your callback at a priority below 10, as the example does. When no callback answers, the model gets {"error":"Unknown tool: <name>"}.

A string result reaches the model as text; anything else is encoded as JSON. In the chatbot and the search answer KimaAI masks card numbers and IBANs in the result while the chatbot’s masking is on (the default), and emails and phone numbers when the settings ask for it; not for a tool marked sensitive in kimaai_tools_registry, and not in the admin assistant. The result is stored with the conversation and, on a streamed answer, sent to the browser with the tool’s progress; a sensitive tool’s result is not. An exception the callback throws reaches the model as {"error": <message>}, and a streamed chat shows that the tool failed.

Parameters

NameTypeDescription
resultmixedNull, or the result an earlier callback returned.
namestringThe tool’s name.
argsarrayThe arguments the model sent, decoded from JSON; empty when they were not valid JSON.
payloadarrayThe request’s payload on a streamed answer, else the payload sent to the provider; both hold chatbot_settings, and the session ID as sessionId or session_id.

Returns

mixed: Null to leave the call to the next callback, else the tool’s result.

Example

add_filter(
  'kimaai_chatbot_tool_call',
  function ($result, string $name, array $args) {
    if ($result !== null || $name !== 'my_delivery_time') {
      return $result;
    }

    $working_days = ['DE' => 2, 'AT' => 3, 'FR' => 4, 'CH' => 5];
    $country = strtoupper((string) ($args['country'] ?? ''));

    return isset($working_days[$country])
      ? ['country' => $country, 'working_days' => $working_days[$country]]
      : ['error' => 'We do not ship to this country.'];
  },
  5,
  3
);

This runs the tool that the page of kimaai_chatbot_tools_registry offers on product pages. When a visitor asks “When does my order arrive in Austria?”, the model calls my_delivery_time with {"country":"AT"} and answers from {"country":"AT","working_days":3}. An error result is for the model, which tells the visitor in its own words.

  • kimaai_chatbot_tools_registry: offers the tool.
  • kimaai_chatbot_allowed_tools: allows its name.
  • kimaai_tool_call_allowed: blocks a call before it reaches this filter.
  • kimaai_chatbot_max_tool_rounds: how many rounds of tool calls an answer may take.
  • kimaai_stream_tool_call: the deprecated name.

What are your feelings