VYG Docs
Tools

Conversations tool

The conversations tool reads your customer text conversations, conversation insights and the trace behind each conversation.

conversations is a read-only tool on https://api.vyg.app/mcp. It needs the conversations:read scope, and insights:read for insights and the conversations behind an insight. Pick what it does with action.

Insights follow the vyg.ai app: the insights action, find with insight_id and the Insights screen are available only to brands with the beta:insight feature, the same brands that see the Insights page. For other brands the action is not offered and insight_id is refused. See Beta features.

ActionWhat it returns
findConversations by topic, behind an insight, or the newest ones with filters.
getOne conversation: its messages, customer contact and checkout, or its trace.
insightsCommon themes customers raise: checkout blockers, post-purchase problems, product questions.

find

find works in one of three ways:

  • query: conversations about a topic, matched on meaning. Returns the best matches in one page.
  • insight_id: the conversations behind one insight, an id from insights.
  • Neither: the newest conversations, with the same filters as the conversation page in the vyg.ai app. status is replied (the customer replied) or recovered (the conversation recovered a sale). Narrow with campaign_ids (one or more campaigns, like the campaign picker in the app; campaign_id still takes one), contact_id, from and to (ISO 8601 dates; a date to covers the whole day). Page with limit (up to 100) and next_cursor.

query and insight_id cannot be combined with the filters. Each row has the customer's name and a one-line message preview. Phone numbers and email addresses are left out; get returns them for one conversation.

{ "action": "find", "status": "recovered", "from": "2026-10-01", "to": "2026-10-07", "limit": 20 }
{ "action": "find", "campaign_ids": ["5b1c…", "9e2d…"], "status": "replied" }

"Which conversations last week recovered a sale?"

get

get takes a conversation_id. By default it returns the messages, the customer's name and phone number or email, the checkout, and goal changes. Add "trace" to include for what started the conversation, each campaign step (entered, skipped and why, sent), the next scheduled send, and whether it recovered the sale.

{ "action": "get", "conversation_id": "0a8f…", "include": ["messages", "trace"] }

"Why did this customer get a text, and did it recover the order?"

insights

insights lists insights with an optional category (blocker, post_purchase, product), tag and day_limit. Pass an insight's id to find as insight_id for example conversations.

{ "action": "insights", "category": "blocker", "limit": 10 }

"What stops shoppers from finishing checkout?"

Replaced tools

conversations replaces search_conversations, list_conversations, get_conversation_details, get_conversation_trace, list_conversation_insights and list_insight_conversations. The old names still work for now and each response names the action to use instead.

On this page