Data Access Tools

Overview

Data Access tools are the backbone of every workflow. Before you can update a widget, edit a chatbot, or check campaign stats, you typically need to find the resource first. These two tools give you read-only access to every resource type in your organization.

list_records

Lists records of a specific resource type in your organization. Returns a summary view of each record (not full details — use get_record for that).

Parameters

Available Resource Types

Boards and Tickets

Real Conversations Only

The same reasoning applies to visitors. Listing visitors returns the people who have actually held a conversation with you, ordered by their most recent conversation. Set includeAnonymous: true when you genuinely want raw page traffic instead — that's the right choice for audience and analytics questions, and it orders by last activity.

What You Get Back

Conversations are sorted newest-updated first, and each response carries two counts:

• total — how many conversations match your filters in total
• returned — how many are in this page

Every conversation record includes the visitor's name, email and country, the text of the last message, the channel it arrived through, the widget name, the email subject (for email conversations), created and updated timestamps, and the assigned agent — so you rarely need a follow-up call just to work out who a conversation is with.

Watching for New Activity

To keep an eye on your inbox without re-reading the whole list every time, remember the newest updated_at you've seen and pass it back as updatedSince on the next call. You'll only get what actually changed.

The difference is dramatic on a busy organization: a full conversation list can run to tens of thousands of records, while the same call with updatedSince set to an hour ago typically returns a handful.

How It Works

• Records are returned sorted by creation date (newest first), except conversations (last update), shifts (start time) and the types that carry their own position — knowledge base categories, documentation categories and pages, conversation starters and shift types — which come back in the order the dashboard shows them.
• The outreach type returns all outreach items grouped by their sub-type (banners, messages, surveys, tours, news).
• Pagination is supported on conversations, visitors, tickets, shifts and subscribers using the from parameter. Other types simply use limit.
• If your account is limited to specific widgets, you only see conversations from those widgets — the same restriction that applies in your Inbox. Owners and admins aren't restricted, and voice calls are always visible since they don't belong to a widget.

Example Prompts

• "Show me all my widgets."
• "List my chatbots."
• "What conversations are unassigned right now?"
• "Show me any conversations that came in since 9am." (uses updatedSince)
• "Show me only my Instagram conversations." (uses channels)
• "Show me the documents in my Support Bot chatbot." (uses list_records to find the chatbot first, then lists its documents)
• "List all published articles in my Support knowledge base." (finds the KB, then lists articles with publishedOnly: true)
• "Show me my newsletter contact groups and how many subscribers each has."
• "Find the subscriber [email protected]." (uses email)
• "List the members of my VIP group." (finds the group, then lists with groupId)
• "Show me unsubscribed contacts." (uses state)
• "What campaigns have I sent recently?"
• "List all my outreach items — banners, surveys, tours, everything."
• "Show me my latest 100 conversations."

get_record

Fetches a single record by ID with full details. Returns more information than list_records — for example, full configuration objects, content fields, and related data.

Parameters

Available Resource Types

All the same types as list_records, plus specific outreach sub-types for fetching individual items:

Two fields on conversations are worth knowing about:

• has_messages — whether this is a real conversation or one of the empty records the widget opens for a new visitor. Unlike list_records, fetching a conversation by ID returns it either way, so this tells you which you got.
• channel — how the conversation arrived: widget, email, Facebook, Instagram, or voice.

How It Works

• The record must belong to your organization. Attempts to access records from other organizations will fail.
• Conversations also respect per-widget access — if your account is limited to specific widgets, fetching a conversation from another widget fails the same way it would in your Inbox.
• Returns the complete details of a resource, giving you the full picture of its configuration and content.

Example Prompts

• "Show me the full details of my default widget." (lists widgets first, then gets the default one)
• "What's the AI configuration on my Support Bot?" (lists chatbots, then gets the specific one)
• "Show me the content of my refund policy document." (lists documents, then gets the full content)
• "Let me see the full HTML of my Getting Started article." (finds the article, then gets its content)
• "What are the trigger rules on my sale banner?" (lists outreach, then gets the banner details)
• "Show me the email content and recipients of my March campaign." (gets campaign with full send details)

Common Workflow Patterns

Explore Then Act

Most workflows start with Data Access tools:

1. List resources to find what exists → list_records
2. Inspect a specific resource to understand its state → get_record
3. Modify it using the appropriate management tool → manage_widget, manage_chatbot, etc.

Bulk Review

Use list_records with a higher limit to review many resources at once:

• "Show me all 200 of my newsletter contacts."
• "List my last 100 conversations."

Monitor for Activity

Check in on your inbox repeatedly without re-reading everything:

1. List conversations once → list_records with table: "chats"
2. Note the newest updated_at in the results
3. On the next check, pass it as updatedSince → only changed conversations come back

• "Check every so often whether any new conversations came in, and tell me about them."

Cross-Reference

Combine listing from different tables to understand relationships:

• "List my widgets and chatbots, then tell me which chatbot is linked to which widget."
• "Show me all knowledge bases and their article counts."