Channels and Conversations

Use the M2M messaging endpoints to connect Visito with your CRM, helpdesk, analytics pipeline, or internal operations backend.

List Channels

Use channels to discover the connected accounts your integration can work with.

GET /m2m/v1/channels

Required scope:

channels:read

Example response:

{
  "channels": [
    {
      "id": "68505cb92a11ea971d9df8bf",
      "tenantId": "tenant_123",
      "type": "whatsapp",
      "provider": "meta",
      "name": "+52 55 1234 5678",
      "active": true,
      "respondEnabled": true,
      "identifiers": {
        "phoneNumberId": "1234567890",
        "phoneNumber": "+52 55 1234 5678",
        "wabaId": "987654321"
      }
    }
  ]
}

Store the channel id when you need to send WhatsApp templates from a specific number.

List Conversations

GET /m2m/v1/conversations

Required scope:

conversations:read

Common query parameters:

Parameter	Values	Default
`limit`	`1` to `200`	`50`
`view`	`all`, `needs_reply`, `handoff`	`all`
`replyState`	`all`, `failed`	`all`
`policyStatus`	`all`, `active`, `archived`, `blocked`	`all`
`responseMode`	`all`, `ai`, `manual`, `frozen`	`all`

Example:

curl "https://platform-api.visitoai.com/m2m/v1/conversations?view=needs_reply&limit=25" \
  -H "Authorization: Bearer $VISITO_M2M_API_KEY"

The endpoint returns the current live window:

{
  "conversations": [
    {
      "conversationId": "conv_123",
      "channel": "whatsapp",
      "participant": {
        "id": "525512345678",
        "displayName": "Sofia"
      },
      "needsReply": true,
      "lastMessageAt": "2026-07-12T18:15:00.000Z",
      "lastMessageText": "Can I check in early?",
      "lastMessageRole": "user",
      "latestReplyStatus": "sent",
      "responseMode": "ai",
      "messageCount": 8
    }
  ],
  "needsReplyCount": 1,
  "handoffCount": 0,
  "hasMore": false,
  "asOf": "2026-07-12T18:15:02.000Z",
  "version": 42,
  "liveWindow": {
    "limit": 25,
    "maxRows": 200,
    "mode": "first_page_realtime"
  }
}

M2M v1 currently exposes the first live conversation window. Even if a response contains nextCursor, the list endpoint does not currently accept a continuation cursor. Use filters and a limit up to 200 to define the working set your integration needs.

Get Conversation Detail

GET /m2m/v1/conversations/{conversationId}

Required scope:

conversations:read

Use this endpoint before sending a reply so your integration has the latest conversation context. Example response:

{
  "conversation": {
    "conversationId": "conv_123",
    "channel": "whatsapp",
    "participant": {
      "id": "525512345678",
      "displayName": "Sofia"
    },
    "needsReply": false,
    "lastMessageAt": "2026-07-12T18:20:00.000Z",
    "lastMessageText": "Hi Sofia, early check-in is available.",
    "lastMessageRole": "assistant",
    "latestReplyStatus": "sent",
    "messageCount": 9
  }
}

conversation.needsReply is the authoritative signal that operator action is required. lastMessageRole describes chronology only; do not use it as a substitute for needsReply.

List Conversation Messages

GET /m2m/v1/conversations/{conversationId}/messages?limit=50&cursor=...

The endpoint returns only the external transcript: inbound user messages and outbound assistant or operator messages. Internal system and tool activity is excluded before pagination. Messages are ordered newest first. Treat cursor as opaque and pass nextCursor unchanged to retrieve older messages. hasMore=true means older external messages remain; nextCursor is null when hasMore=false. Example response:

{
  "conversationId": "conv_123",
  "messages": [
    {
      "messageId": "message_123",
      "eventId": "evt_123",
      "direction": "outbound",
      "role": "assistant",
      "text": "Hi Sofia, early check-in is available.",
      "createdAt": "2026-07-12T18:20:00.000Z",
      "status": "sent",
      "author": {
        "type": "operator",
        "operatorName": "CRM automation",
        "displayName": "CRM automation"
      },
      "media": []
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Use messages[].eventId to correlate a queued requestEventId. Delivery information can appear in messages[].status, messages[].statusReason, and messages[].deliveries. status is always one of received, queued, sent, delivered, read, failed, blocked, partial_sent, or unknown. A dispatcher publish failure is normalized to failed. Message direction describes chronology only. Use conversation.needsReply, not the latest message direction, to decide whether operator action is required.

Send a Reply

POST /m2m/v1/conversations/{conversationId}/reply

Required scope:

conversations:write

Required headers:

Authorization: Bearer visito_m2m_...
Idempotency-Key: crm-reply-123
Content-Type: application/json

Request body:

{
  "text": "Hi Sofia, your reservation has been updated.",
  "replyToExternalMessageId": "wamid.optional-reference"
}

You can send text, media, or both:

{
  "text": "Here is the updated receipt.",
  "mediaId": "media_123"
}

M2M v1 does not currently expose a media-upload endpoint. mediaId can only reference a media asset that already exists for the conversation. For a standalone M2M integration, use text replies unless your workflow already has a valid Visito media ID.

Successful response:

{
  "accepted": true,
  "replyId": "reply_123",
  "conversationId": "conv_123",
  "requestEventId": "evt_123",
  "correlationId": "corr_123",
  "status": "queued",
  "acceptedAt": "2026-07-12T18:20:00.000Z"
}

Replies are queued asynchronously. Delivery results are reconciled into Visito conversation history after the channel dispatcher sends the message.

Reconcile an Outbound Reply

Persist the conversationId, replyId, requestEventId, correlationId, and Idempotency-Key from the 202 response.
Read GET /m2m/v1/conversations/{conversationId}/messages.
Match requestEventId to messages[].eventId.
Treat queued as pending, sent as handed to the provider, and failed or blocked as unsuccessful.
If the original send request times out, retry the exact same body with the same idempotency key before deciding to create new outbound work.

Free-form replies can return 409 REPLY_WINDOW_CLOSED. For WhatsApp, use an approved template to reopen the conversation instead of retrying the reply.

When To Use WhatsApp Templates

WhatsApp and Instagram have provider rules around free-form messages. For WhatsApp conversations outside the customer service window, use an approved WhatsApp template instead of a free-form reply. Continue with WhatsApp Templates to create, list, and send templates.

Build With Visito

AI Coding Assistants

List Channels

List Conversations

Get Conversation Detail

List Conversation Messages

Send a Reply

Reconcile an Outbound Reply

When To Use WhatsApp Templates

​List Channels

​List Conversations

​Get Conversation Detail

​List Conversation Messages

​Send a Reply

​Reconcile an Outbound Reply

​When To Use WhatsApp Templates

List Channels

List Conversations

Get Conversation Detail

List Conversation Messages

Send a Reply

Reconcile an Outbound Reply

When To Use WhatsApp Templates