MCP is live.Set upAsk the community
OmniDimension
Dashboard
DocumentationAPI referenceSDKsMCP
WhatsApp

List conversations

A number's inbox, newest activity first. Poll it with updated_since for changes since your last call, or page it with cursor. There are no event webhooks, so polling is how an integration learns about new messages.

Set up WhatsApp first. Connect a WhatsApp number in the dashboard or with Connect numbers. Included on every paid plan. See plans.

GET/whatsapp/numbers//conversations
Path parameters
number_idrequired
Query parameters
filterstring · enum

needs_person is a person-owned or paused conversation. window_closed is one you can only reach with a template.

qstring

Search the customer's name, phone number and message text.

updated_sincestring

An ISO 8601 date and time, such as 2026-10-01T09:00:00+00:00. Returns conversations with a change at or after it. No offset means UTC.

limitinteger

Rows per page.

cursorstring

The next_cursor from the previous page.

curl -X GET 'https://backend.omnidim.io/api/v1/whatsapp/numbers/{number_id}/conversations?filter=all&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example response
synthetic
{
  "data": [
    {
      "id": "412-15551234567",
      "phone_number_id": 0,
      "customer_phone": "+15551234567",
      "customer_name": "string",
      "last_message": {
        "preview": "string",
        "type": "string",
        "sender": "customer",
        "timestamp": "string",
        "status": "pending"
      },
      "last_message_at": "string",
      "unread_count": 0,
      "message_count": 0,
      "ownership": {
        "owner": "person",
        "paused": false
      },
      "window_open": false,
      "window_expires_at": "string",
      "has_failed": false,
      "opted_out": false,
      "campaign": {
        "id": 0,
        "name": "string"
      }
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

Authorization

BearerAuth
headerAuthorizationBearer <token>

Bearer token authentication. Obtain your API key from the OmniDimension dashboard.

Path Parameters

number_id*integer

Id of a WhatsApp number in your workspace, from listWhatsappNumbers. A number in another workspace answers 404.

Query Parameters

filter?string

needs_person is a person-owned or paused conversation. window_closed is one you can only reach with a template.

Default"all"
Value in"all""unread""needs_person""agent""failed""window_closed""campaign_replies"
q?string

Search the customer's name, phone number and message text.

Lengthlength <= 200
updated_since?string

An ISO 8601 date and time, such as 2026-10-01T09:00:00+00:00. Returns conversations with a change at or after it. No offset means UTC.

limit?integer

Rows per page.

Range1 <= value <= 100
Default20
cursor?string

The next_cursor from the previous page.

Response body

application/json

Response Body

One page of conversations.

application/json
data?
has_more?boolean
next_cursor?string

Turn calling on or off

Turn calling on or off for a Meta Cloud number. A customer calls this number; it does not place calls. Turning it on requires every blocking check to pass, or the request answers 409. Turning it off is always allowed.

Get a conversation

One conversation: who owns it, the 24-hour window, whether the customer opted out, and the unread count. Poll it while a person is answering.