List Conversations

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 week

Example 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 checkoutState to filter by outcome — recovered for successful recoveries, abandoned for lost carts
• Combine workflowId with date filters to analyze a specific flow’s conversations
• For topic-based searching (e.g., “conversations about shipping”), use conversation-search instead
• Use get_conversation_details to read the full thread of any conversation