MCPTools
List Conversations
Filter and browse conversations by date, status, or workflow
list_conversations
List and filter conversations by date range, checkout state, workflow, and response status. Returns conversation summaries with customer info and the latest message.
Parameters
| Name | Type | Required | Description | Default |
|---|---|---|---|---|
from | string | No | Start date in ISO format (e.g., 2024-01-01T00:00:00Z) | — |
to | string | No | End date in ISO format (e.g., 2024-01-31T23:59:59Z) | — |
checkoutState | string[] | No | Filter by checkout state(s): abandoned, recovered, messaged, initial, filtered, skipped, complete | — |
workflowId | string | No | Filter by workflow ID (get IDs from list_workflows) | — |
hasResponse | boolean | No | Only return conversations where the customer replied | — |
limit | number | No | Max results per page (1–50) | 20 |
offset | number | No | Pagination offset | 0 |
Example Prompt
Show me recovered conversations from this weekExample Response
{
"conversations": [
{
"id": "conv-789",
"createdAt": "2025-01-28T14:30:00Z",
"customer": {
"name": "John Smith",
"phone": "+15559876543"
},
"workflowName": "Abandoned Cart - Main",
"checkoutState": "recovered",
"lastMessage": {
"body": "Thanks! Just completed my order 🎉",
"direction": "inbound",
"createdAt": "2025-01-28T15:10:00Z"
}
}
],
"totalCount": 42,
"limit": 20,
"offset": 0
}Notes
- Use
checkoutStateto filter by outcome —recoveredfor successful recoveries,abandonedfor lost carts - Combine
workflowIdwith date filters to analyze a specific flow's conversations - For topic-based searching (e.g., "conversations about shipping"), use
conversation-searchinstead - Use
get_conversation_detailsto read the full thread of any conversation