Chatbot Tools

Overview

The Chatbot tool category covers Yaplet's AI agent — the one the dashboard calls Vex. You can change its settings, feed it knowledge through documents, and investigate when it gives a wrong or unexpected answer.

manage_chatbot

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

Parameters

How It Works

Creating an agent:

• Only name is required. The agent 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)
  • Privacy masking: disabled
• The agent starts inactive by default. Set active: true to enable it immediately.

Updating an agent:

• Provide the id and only the fields you want to change.
• The noContextBehavior setting is the one that most affects answer quality:
  • "decline" — The AI politely says it doesn't have information on that topic. This is the safe default.
  • "offer_agent" — The AI offers to connect the visitor with a human. It needs agent handoff switched on; if handoff is off, the setting quietly falls back to decline.
• The parameters above are the only agent settings any tool can write. In particular, nothing here changes the agent's answer instructions (its free-text prompt) or its emoji setting — the two settings that decide how it writes. Those are edited on Brand → Vex → Personality.

Example Prompts

• "Activate my AI agent."
• "Set my agent to hand off to a human after 3 unanswered messages."
• "Change the no-context behavior to decline instead of offering an agent."
• "Disable agent handoff."
• "Set the agent handoff message to 'Let me connect you with a support specialist.'"
• "Rename my AI agent to 'Ada'."
• "Turn my AI agent off for now."

manage_chatbot_document

Creates or updates a text document in the brand's knowledge. 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 sanitized, split into chunks and indexed so the AI can retrieve it when answering questions.
• Once indexed, the AI can immediately use this knowledge — on chat, on the phone, in suggested inbox replies, and in AI social posts.

Updating a document:

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

Example Prompts

• "Add a document explaining our refund policy: customers can get a full refund within 30 days."
• "Create a knowledge document 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 covering these topics: account setup, password reset, and billing questions."
• "Fix the knowledge gap — add a document about our return process." (typically follows a diagnose step)

diagnose_ai_response

Analyzes why the AI gave a specific answer. Returns a detailed diagnostic report with the question asked, the answer given, the knowledge it actually read, the agent's settings, and actionable suggestions.

Parameters

How It Works

1. Finds the AI interaction linked to the message — the visitor's question, the AI's answer, the search queries it ran, the exact text of every knowledge chunk it read with a relevance score, any API tool it called with what it sent and got back, 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. Reports the settings that may have contributed, including the agent's full answer instructions verbatim, its no-context behavior, its handoff configuration, whether smart answer matching is on, and whether privacy masking is on.
4. Provides actionable suggestions — typically recommending that you add a knowledge document to fill the gap, or adjust the agent's settings.

How to Get the Message ID

Use get_conversation_messages to read the messages in a conversation. AI answers are clearly identified in the results. The message id of an AI answer is what you pass to diagnose_ai_response. For answers given before Yaplet started linking AI events to messages, the tool cannot analyze them automatically — instead it hands you a direct link to that brand's Vex → Reports page, where you can find the answer in the table and expand its row to see the same detail.

Example Prompts

• "The AI 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 fail to answer the customer's question about pricing?"
• "Diagnose the AI response for the message where it talked about shipping."
• "Check why the AI escalated to a human agent in the latest conversation."
• "The AI said something incorrect — diagnose it and fix the knowledge." (diagnoses, identifies the gap, then uses manage_chatbot_document to add the missing info)

Common Workflow Patterns

Complete AI Agent Setup

1. Create the agent on Brand → Vex (in the dashboard, so it belongs to your brand)
2. Add knowledge documents → manage_chatbot_document (repeat for each topic)
3. Activate → manage_chatbot with active: true

Example prompt: "Add documents about our refund policy and shipping info to my AI agent, then 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 AI failed, diagnose the most recent one, and add a document to fix the issue."