Conversation Tools

Overview

The Conversation tool category gives you full access to your live chat inbox. You can read message history, search for conversations by content, assign or transfer chats between agents, and send messages (including private internal notes).

get_conversation_messages

Fetches messages from a specific conversation in chronological order.

Parameters

How It Works

• Returns messages sorted chronologically (oldest first in the result set).
• Each message includes its content, timestamp, sender information, and whether it's a public message or a private agent note.
• AI chatbot messages are clearly identified, making it easy to find messages to pass to diagnose_ai_response.
• Returns a total message count for pagination.
• The conversation must belong to your organization, and to a widget you have access to.

Example Prompts

• "Show me the messages in this conversation." (after identifying the chat from list_records or search_conversations)
• "What did the customer say in the latest chat?"
• "Read the last 100 messages from conversation X."
• "Show me the older messages in this chat — page 2."
• "Find the AI chatbot's responses in this conversation." (looks for messages where chatbot_id is set)

search_conversations

Searches across the conversations in your organization by message content, the person involved, the assigned agent, or conversation ID.

Parameters

Search Types

How It Works

• Results are sorted newest-updated first, so the most relevant recent conversations come back first.
• Each response includes total (how many conversations matched in total) and returned (how many are in this page), so you can tell whether you're seeing everything.
• Only real conversations are searched. The empty records the widget opens for every new visitor are never returned.
• External callers (OAuth) only search public messages — private agent notes are excluded.
• Returns matching conversations (not individual messages), each with the visitor's name and email, the last message, the channel, the state and timestamps — you can then use get_conversation_messages to read the full thread.

Example Prompts

• "Search for conversations about refunds."
• "Find chats where someone mentioned 'billing issue'."
• "Find all conversations with [email protected]." (uses searchType: "visitor")
• "Which conversations is Sarah handling?" (uses searchType: "agent")
• "Search for the conversation with ID starting with abc123."
• "Find any conversations about password reset problems."

assign_conversation

Assigns a conversation to a specific agent, transfers it between agents, or unassigns it.

Parameters

How It Works

Assigning/transferring:

• The target agent must be a member of your organization.
• A system message is added to the conversation noting the transfer.
• The conversation's assigned agent is updated.

Unassigning:

• Removes the assigned agent from the conversation.
• The conversation moves to the "Unassigned" inbox category.

Example Prompts

• "Assign this conversation to me."
• "Transfer the chat to agent John." (would need to find John's user ID first)
• "Unassign this conversation so anyone can pick it up."
• "Move all unassigned chats to my inbox." (lists unassigned chats, then assigns each one)
• "Transfer this conversation to the support team lead."

send_conversation_message

Sends a text message in a conversation as the current agent.

Parameters

How It Works

• Requires a user session (session or OAuth).
• Public messages are delivered to the visitor in real-time through the chat widget.
• Private notes are only visible to other agents in the dashboard — the visitor never sees them.
• Email delivery: When sendAsEmail: true, the message is also sent as an email to the visitor's email address (if known).
• External callers cannot create private notes.

Example Prompts

• "Reply to the customer saying 'Thanks for reaching out! I'll look into this right away.'"
• "Send a message in conversation X: 'Your refund has been processed and you should see it within 3-5 business days.'"
• "Add a private note to this conversation: 'Customer is on the enterprise plan, prioritize.'"
• "Reply to the visitor and also send it as an email."
• "Send a private note: 'Checked with the billing team — refund approved.'"

Common Workflow Patterns

Inbox Triage

1. List unassigned conversations → list_records with table: "chats", category: "unassigned"
2. Read the latest messages → get_conversation_messages
3. Assign to the right agent → assign_conversation

Example prompt: "Show me all unassigned conversations, read the latest messages in each, and assign any billing-related ones to me."

Search and Respond

1. Search for a topic → search_conversations
2. Read the conversation → get_conversation_messages
3. Send a reply → send_conversation_message

Example prompt: "Find conversations mentioning 'refund', show me the most recent one, and send a reply saying the refund has been processed."

Follow a Customer's History

1. Find everything from one person → search_conversations with searchType: "visitor"
2. Read each conversation → get_conversation_messages

Example prompt: "Find every conversation we've had with [email protected] and summarise what they've contacted us about."

Investigate and Document

1. Search for the issue → search_conversations
2. Read the conversation → get_conversation_messages
3. Diagnose AI failure → diagnose_ai_response (from Chatbot tools)
4. Fix the knowledge gap → manage_chatbot_document (from Chatbot tools)

Example prompt: "Find any conversations where the chatbot failed to answer, diagnose the issue, and create a document to fix the knowledge gap."