VIvisitoai
Conversations

List conversations with cursor pagination

Use to find a guest conversation or sample common topics across the inbox. Search stored guest identity with contactQuery and channel; participant.displayName and optional participant.phone identify the contact. list_assignable_operators lists staff, not guests. For exports defined by executed actions, use actionId and optional actionStatus before reading messages. Filters match saved projected action history; rows remain ordered by lastMessageAt, not latest action time. Query each desired action ID and deduplicate conversationId when combining results. For actions executed in a specific period use list_action_executions with from/to; missing projected history does not prove no action ran. This is not message-text search or an account-wide topic report. Requires conversations:read. Pass nextCursor as cursor with the same filters while hasMore is true. Ordered by lastMessageAt descending, then conversationId ascending. This is a live list, not a frozen snapshot; new activity can move a conversation ahead of a previously read boundary. Invalid cursors return 400 M2M_INVALID_REQUEST. Optional conversation.aiSummary describes main topics and current state. Read summaries first; fetch messages when the summary is absent, isStale is true, or supporting detail is needed. Summaries do not replace authoritative needsReply, booking, payment or delivery fields.

get/conversations

Request

  • Base URL
    https://platform-api.visitoai.com/m2m/v1
  • Auth
    HTTP bearer

Query parameters

limitinteger
cursorstring

Opaque nextCursor from the previous conversation-list response. Omit for the first page. Keep filters unchanged.

view'all' | 'needs_reply' | 'handoff'
replyState'all' | 'failed'
policyStatus'all' | 'active' | 'archived' | 'blocked'
responseMode'all' | 'ai' | 'manual' | 'frozen'
optedOutboolean

Filter conversations by the current contact opt-out state.

contactQuerystring

Search stored contact identity by name or contact details; not message text. Check participant fields in each match before selecting a recipient.

channel'all' | 'whatsapp' | 'instagram' | 'messenger' | 'tiktok' | 'webchat'

Filter to the intended messaging channel when locating a guest.

ownerstring

Discovered operator ID or all; use list_assignable_operators for staff IDs. Do not pass mine.

actionIdstring

Find conversations with recorded executions of this canonical action ID (for example hospitality.find_options, hospitality.quote_stay or hospitality.checkout). Covers saved projected history, not an action execution date range. Use list_action_executions for dated activity.

actionStatus'all' | 'running' | 'completed' | 'failed'

Requires actionId. Match conversations with at least one recorded running, completed or failed execution of that action; all matches any recorded status. Completion does not establish a booking or payment. Preserve both filters when paginating.

Response

Conversation page with hasMore and optional nextCursor

needsReplyCountinteger required
handoffCountinteger required
nextCursorstring
hasMoreboolean required
asOfstring date-time required
versioninteger required

Changes

No recorded changes to this operation across all 1 revision of this API.