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.

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 all conversations in your organization by message content or chat ID.

Parameters

How It Works

• Searches message content across all organization conversations.
• External callers (OAuth) only search public messages — private agent notes are excluded.
• Returns matching conversations (not individual messages) — you can then use get_conversation_messages to read the specific messages.

Example Prompts

• "Search for conversations about refunds."
• "Find chats where someone mentioned 'billing issue'."
• "Look for conversations mentioning a specific product name."
• "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."

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