List messages

GET /v1/messages

Returns a page of your workspace’s messages, incoming and outgoing, newest first. Use it to catch up after your webhook endpoint was down.

Needs messages:read.

Messages with one contact

curl "https://app.soosh.io/v1/messages?contact_id=4ea0d485-435d-407f-837a-c7d67095f23a&limit=20" \
  -H "Authorization: Bearer $SOOSH_API_KEY"

const res = await fetch('https://app.soosh.io/v1/messages?contact_id=4ea0d485-435d-407f-837a-c7d67095f23a&limit=20', {
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://app.soosh.io/v1/messages?contact_id=4ea0d485-435d-407f-837a-c7d67095f23a&limit=20",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}"},
)
print(res.json())

Response200

{
  "data": [
    {
      "id": "8c2e4f6a-1d3b-4a5c-9e7f-2b4d6f8a0c1e",
      "contact_id": "4ea0d485-435d-407f-837a-c7d67095f23a",
      "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
      "direction": "outgoing",
      "type": "text",
      "status": "delivered",
      "text": {
        "body": "Your order has shipped."
      },
      "media": null,
      "template": null,
      "interactive": null,
      "reply_to_message_id": null,
      "whatsapp_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQzc0RkJBMEY3QjI5RDdFNjk3AA==",
      "error": null,
      "sent_by": {
        "type": "api_key",
        "id": "5e1d2c3b-4a59-4f68-8e7d-6c5b4a392817",
        "name": "Order system"
      },
      "broadcast_id": null,
      "created_at": "2026-10-14T09:30:12.481Z",
      "updated_at": "2026-10-14T09:30:15.902Z"
    }
  ],
  "next_cursor": null
}

Every field of the message object

Query parameters

limit integer

How many items to return.

From 1 to 100. Default 25.

cursor string

The next_cursor of the previous page, unchanged. A cursor that was changed, or made for a different sort, is 400 invalid_request.

sort string

created_at lists newest first. updated_at lists oldest change first.

Default created_at.

contact_id string · uuid

Only messages with this contact. A contact of another workspace is 422 invalid_field.

number_id string · uuid

Only messages sent from or to this number. A number of another workspace is 422 invalid_field.

direction string

Only incoming or only outgoing messages.

One of incoming outgoing.

updated_after string · date-time

Only messages changed after this time (RFC 3339). A change shows up about 30 seconds after it’s saved. The list runs oldest change first, so leave sort out or set it to updated_at.

Syncing changes

With sort=updated_at, a message moves to the end of the list each time its status changes. Resume a minute early and skip messages you already have. See Pagination.

Listing doesn't mark messages as read

The contact gets no read receipt when you list or fetch a message.

Returns

200 A page of message objects. A page of messages.

Errors

Besides the ones every request can get:

422invalid_fieldThe contact_id or number_id isn’t in your workspace.