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

curl --request GET \
  --url https://platform-api.visitoai.com/m2m/v1/conversations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://platform-api.visitoai.com/m2m/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform-api.visitoai.com/m2m/v1/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://platform-api.visitoai.com/m2m/v1/conversations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://platform-api.visitoai.com/m2m/v1/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "conversations": [
    {
      "conversationId": "<string>",
      "tenantId": "<string>",
      "channel": "whatsapp",
      "participant": {
        "id": "<string>",
        "displayName": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "username": "<string>",
        "avatarUrl": "<string>",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "unreadCount": 123,
      "needsReply": true,
      "lastMessageAt": "2023-11-07T05:31:56Z",
      "lastMessageText": "<string>",
      "lastMessageRole": "<string>",
      "messageCount": 123,
      "conversationKey": "<string>",
      "latestReplyStatus": "queued",
      "policyStatus": "active",
      "responseMode": "ai",
      "frozenUntilAt": "2023-11-07T05:31:56Z",
      "needsReplySince": "2023-11-07T05:31:56Z",
      "needsReplyReason": "<string>",
      "needsReplyDetail": "<string>",
      "unreadUpdatedAt": "2023-11-07T05:31:56Z",
      "handoffStatus": "none",
      "activeHandoffCaseId": "<string>",
      "handoffRequestedAt": "2023-11-07T05:31:56Z",
      "handoffResolvedAt": "2023-11-07T05:31:56Z",
      "handoffReasonCode": "<string>",
      "handoffReasonDetail": "<string>",
      "handoffIntentId": "<string>",
      "handoffTitleKey": "<string>",
      "handoffTitleFallback": "<string>",
      "handoffOperatorNote": "<string>",
      "handoffPropertyId": "<string>",
      "handoffPropertyDisplayName": "<string>",
      "handoffSeverity": "hard",
      "handoffCapturedFieldsDisplay": [
        {
          "id": "<string>",
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "handoffMissingFieldsDisplay": [
        {
          "id": "<string>",
          "label": "<string>"
        }
      ],
      "reviewStatus": "none",
      "activeReviewCaseId": "<string>",
      "reviewReasonCode": "<string>",
      "reviewNote": "<string>",
      "reviewRequestedAt": "2023-11-07T05:31:56Z",
      "reviewResolvedAt": "2023-11-07T05:31:56Z",
      "assignedOperatorId": "<string>",
      "assignedOperatorName": "<string>",
      "assignedAt": "2023-11-07T05:31:56Z",
      "latestReplyAt": "2023-11-07T05:31:56Z",
      "manualEnabled": true,
      "optedOut": true,
      "optedOutAt": "2023-11-07T05:31:56Z",
      "optedOutReason": "user_stop",
      "lastMessageEventId": "<string>",
      "senderId": "<string>",
      "recipientId": "<string>",
      "handoffAvailability": {
        "status": "within_hours",
        "timezone": "<string>",
        "evaluatedAtLocal": "<string>",
        "currentWindow": {
          "date": "<string>",
          "day": "<string>",
          "start": "<string>",
          "end": "<string>"
        },
        "nextWindow": {
          "date": "<string>",
          "day": "<string>",
          "start": "<string>",
          "end": "<string>"
        }
      },
      "aiSummary": {
        "text": "<string>",
        "generatedAt": "2023-11-07T05:31:56Z",
        "throughMessageAt": "2023-11-07T05:31:56Z",
        "isStale": true
      }
    }
  ],
  "needsReplyCount": 123,
  "handoffCount": 123,
  "hasMore": true,
  "asOf": "2023-11-07T05:31:56Z",
  "version": 123,
  "liveWindow": {
    "limit": 123,
    "maxRows": 123,
    "mode": "first_page_realtime"
  },
  "nextCursor": "<string>"
}

{
  "error": {
    "code": "M2M_AUTH_INSUFFICIENT_SCOPE",
    "message": "M2M credential does not have required scope.",
    "details": {
      "requiredScopes": [
        "conversations:write"
      ],
      "missingScopes": [
        "conversations:write"
      ]
    }
  }
}

Authorizations

Authorization

string

header

required

Server-side tenant-scoped credential created from Build > API Keys.

Query Parameters

limit

integer

default:50

Required range: 1 <= x <= 200

cursor

string

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

Maximum string length: 2048

view

enum<string>

default:all

Available options:

all,

needs_reply,

handoff

replyState

enum<string>

default:all

Available options:

all,

failed

policyStatus

enum<string>

default:all

Available options:

all,

active,

archived,

blocked

responseMode

enum<string>

default:all

Available options:

all,

ai,

manual,

frozen

optedOut

boolean

Filter conversations by the current contact opt-out state.

contactQuery

string

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

Required string length: 2 - 200

channel

enum<string>

Filter to the intended messaging channel when locating a guest.

Available options:

all,

whatsapp,

instagram,

messenger,

tiktok,

webchat

owner

string

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

Maximum string length: 24

Pattern: ^(all|[a-fA-F0-9]{24})$

actionId

string

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.

Required string length: 1 - 200

actionStatus

enum<string>

default:all

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.

Available options:

all,

running,

completed,

failed

Response

Conversation page with hasMore and optional nextCursor

conversations

object[]

required

Show child attributes

needsReplyCount

integer

required

handoffCount

integer

required

hasMore

boolean

required

asOf

string<date-time>

required

version

integer

required

liveWindow

object

required

Show child attributes

nextCursor

string

List conversations with cursor pagination

curl --request GET \
  --url https://platform-api.visitoai.com/m2m/v1/conversations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://platform-api.visitoai.com/m2m/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform-api.visitoai.com/m2m/v1/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://platform-api.visitoai.com/m2m/v1/conversations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://platform-api.visitoai.com/m2m/v1/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "conversations": [
    {
      "conversationId": "<string>",
      "tenantId": "<string>",
      "channel": "whatsapp",
      "participant": {
        "id": "<string>",
        "displayName": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "username": "<string>",
        "avatarUrl": "<string>",
        "updatedAt": "2023-11-07T05:31:56Z"
      },
      "unreadCount": 123,
      "needsReply": true,
      "lastMessageAt": "2023-11-07T05:31:56Z",
      "lastMessageText": "<string>",
      "lastMessageRole": "<string>",
      "messageCount": 123,
      "conversationKey": "<string>",
      "latestReplyStatus": "queued",
      "policyStatus": "active",
      "responseMode": "ai",
      "frozenUntilAt": "2023-11-07T05:31:56Z",
      "needsReplySince": "2023-11-07T05:31:56Z",
      "needsReplyReason": "<string>",
      "needsReplyDetail": "<string>",
      "unreadUpdatedAt": "2023-11-07T05:31:56Z",
      "handoffStatus": "none",
      "activeHandoffCaseId": "<string>",
      "handoffRequestedAt": "2023-11-07T05:31:56Z",
      "handoffResolvedAt": "2023-11-07T05:31:56Z",
      "handoffReasonCode": "<string>",
      "handoffReasonDetail": "<string>",
      "handoffIntentId": "<string>",
      "handoffTitleKey": "<string>",
      "handoffTitleFallback": "<string>",
      "handoffOperatorNote": "<string>",
      "handoffPropertyId": "<string>",
      "handoffPropertyDisplayName": "<string>",
      "handoffSeverity": "hard",
      "handoffCapturedFieldsDisplay": [
        {
          "id": "<string>",
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "handoffMissingFieldsDisplay": [
        {
          "id": "<string>",
          "label": "<string>"
        }
      ],
      "reviewStatus": "none",
      "activeReviewCaseId": "<string>",
      "reviewReasonCode": "<string>",
      "reviewNote": "<string>",
      "reviewRequestedAt": "2023-11-07T05:31:56Z",
      "reviewResolvedAt": "2023-11-07T05:31:56Z",
      "assignedOperatorId": "<string>",
      "assignedOperatorName": "<string>",
      "assignedAt": "2023-11-07T05:31:56Z",
      "latestReplyAt": "2023-11-07T05:31:56Z",
      "manualEnabled": true,
      "optedOut": true,
      "optedOutAt": "2023-11-07T05:31:56Z",
      "optedOutReason": "user_stop",
      "lastMessageEventId": "<string>",
      "senderId": "<string>",
      "recipientId": "<string>",
      "handoffAvailability": {
        "status": "within_hours",
        "timezone": "<string>",
        "evaluatedAtLocal": "<string>",
        "currentWindow": {
          "date": "<string>",
          "day": "<string>",
          "start": "<string>",
          "end": "<string>"
        },
        "nextWindow": {
          "date": "<string>",
          "day": "<string>",
          "start": "<string>",
          "end": "<string>"
        }
      },
      "aiSummary": {
        "text": "<string>",
        "generatedAt": "2023-11-07T05:31:56Z",
        "throughMessageAt": "2023-11-07T05:31:56Z",
        "isStale": true
      }
    }
  ],
  "needsReplyCount": 123,
  "handoffCount": 123,
  "hasMore": true,
  "asOf": "2023-11-07T05:31:56Z",
  "version": 123,
  "liveWindow": {
    "limit": 123,
    "maxRows": 123,
    "mode": "first_page_realtime"
  },
  "nextCursor": "<string>"
}

{
  "error": {
    "code": "M2M_AUTH_INSUFFICIENT_SCOPE",
    "message": "M2M credential does not have required scope.",
    "details": {
      "requiredScopes": [
        "conversations:write"
      ],
      "missingScopes": [
        "conversations:write"
      ]
    }
  }
}

Start here

Browse endpoints

List conversations with cursor pagination

Authorizations

Query Parameters

Response