Chatbot Tools

Overview

The Chatbot tool category covers everything related to Yaplet's AI chatbot system. You can create chatbots, feed them knowledge through documents, tune their behavior, and investigate when they give wrong or unexpected answers.

manage_chatbot

Creates a new AI chatbot or updates an existing one's settings.

Parameters

How It Works

Creating a chatbot:

• Only name is required. The chatbot is created with sensible defaults:
  • Type: AI
  • No-context behavior: decline (politely refuse unknown questions)
  • Agent handoff: enabled, threshold of 6 messages
  • Reranking: enabled (smart answer matching)
  • PII masking: disabled
• The chatbot starts inactive by default. Set active: true to enable it immediately.

Updating a chatbot:

• Provide the id and only the fields you want to change.
• The noContextBehavior setting is critical for AI quality:
  • "decline" — Safest option. The AI politely says it doesn't have information on that topic.
  • "request_agent" — The AI hands off to a human agent when it can't find an answer.
  • "answer" — The AI attempts to answer using general knowledge. This can produce inaccurate responses and is generally not recommended.

Example Prompts

• "Create a chatbot called Support Bot."
• "Create a chatbot named Sales Assistant and activate it immediately."
• "Activate my Support Bot chatbot."
• "Set my chatbot to hand off to a human agent after 3 unanswered messages."
• "Change the no-context behavior to decline instead of guessing."
• "Disable agent handoff on my chatbot."
• "Set the agent handoff message to 'Let me connect you with a support specialist.'"

manage_chatbot_document

Creates or updates a text document in a chatbot's knowledge base. Documents are automatically processed so the AI can use them to answer questions.

Parameters

How It Works

Creating a document:

• Provide chatbotId, name, and content.
• The content is automatically processed and indexed so the chatbot can retrieve it when answering questions.
• Once indexed, the chatbot can immediately use this knowledge to answer visitor questions.

Updating a document:

• Provide the id and the fields to change (name and/or content).
• On update, the AI index is rebuilt from the new content.
• This means changes take effect immediately — the chatbot uses the updated knowledge right away.

Example Prompts

• "Add a document to my chatbot explaining our refund policy: customers can get a full refund within 30 days."
• "Create a knowledge document for the Sales Bot about our pricing tiers."
• "Update the shipping policy document with the new international shipping rates."
• "Rename the FAQ document to 'Frequently Asked Questions - 2026'."
• "Add a document to my chatbot covering these topics: account setup, password reset, and billing questions."
• "Fix the chatbot's knowledge gap — add a document about our return process." (typically follows a diagnose step)

diagnose_ai_response

Analyzes why an AI chatbot gave a specific answer. Returns a detailed diagnostic report with the question asked, the answer given, the knowledge context used, chatbot settings, and actionable suggestions.

Parameters

How It Works

1. Finds the AI interaction linked to the message — including the visitor's question, the AI's answer, what knowledge was retrieved, and the model used.
2. Classifies the outcome — Was the answer based on relevant knowledge? Did the AI lack context? Was the visitor handed off to a human agent? Did a technical error occur?
3. Checks chatbot settings that may have contributed to the issue (no-context behavior, custom instructions, knowledge retrieval settings).
4. Provides actionable suggestions — typically recommending that you add a knowledge document to fill the gap, or adjust chatbot settings.

How to Get the Message ID

Use get_conversation_messages to read the messages in a conversation. AI chatbot answers are clearly identified in the results. The message id of an AI answer is what you pass to diagnose_ai_response.

Example Prompts

• "The chatbot gave a wrong answer in conversation X. Can you diagnose what happened?" (reads messages first, finds the AI answer, then diagnoses)
• "Why did the AI chatbot fail to answer the customer's question about pricing?"
• "Diagnose the AI response for the message where the chatbot talked about shipping."
• "Check why the chatbot escalated to a human agent in the latest conversation."
• "The chatbot said something incorrect — diagnose it and fix the knowledge base." (diagnoses, identifies the gap, then uses manage_chatbot_document to add the missing info)

Common Workflow Patterns

Complete Chatbot Setup

1. Create the chatbot → manage_chatbot
2. Add knowledge documents → manage_chatbot_document (repeat for each topic)
3. Link to widget → link_to_widget (from Widget tools)
4. Activate → manage_chatbot with active: true

Example prompt: "Create a chatbot called Support Bot, add documents about our refund policy and shipping info, link it to my default widget, and activate it."

Diagnose and Fix

1. Find the conversation → search_conversations or list_records
2. Read the messages → get_conversation_messages
3. Diagnose the AI answer → diagnose_ai_response
4. Fix the knowledge gap → manage_chatbot_document

Example prompt: "Find conversations where the chatbot failed, diagnose the most recent one, and add a document to fix the issue."