Read API

Overview

The read API lets your bot pull conversation history on demand — to build its own chat UI, backfill state after a restart, or debug — without keeping a perfectly synced copy of every webhook event. It is a narrow, provider-agnostic projection of the inbox; it never exposes internal rows, counters, or tokens. Permission: WhatsApp on both endpoints. Every query is scoped to the API key’s company — a chat that belongs to another company returns a clean 404.

List conversations

GET https://api.minimo.it/public/v1/whatsapp/conversations

Newest activity first.

Query parameters

Parameter	Type	Default	Description
`page`	number	`1`	1-based page number.
`pageSize`	number	`20`	Items per page. Clamped to a maximum of 100.

curl "https://api.minimo.it/public/v1/whatsapp/conversations?page=1&pageSize=20" \
  -H "Authorization: Bearer mn-abc123-xyz789"

Response

{
  "data": [
    {
      "chatId": 1234,
      "contact": {
        "id": 5678,
        "phone": "393391234567",
        "name": "Mario Rossi"
      },
      "status": "open",
      "unreadMessages": 2,
      "lastMessage": {
        "text": "Ciao, vorrei informazioni sul contratto",
        "direction": "inbound",
        "timestamp": 1760000000,
        "timestampIso": "2025-10-09T07:33:20.000Z"
      },
      "createdAt": "2025-10-01T09:00:00.000Z",
      "updatedAt": "2025-10-09T07:33:20.000Z"
    }
  ],
  "pagination": {
    "totalRecords": 42,
    "currentPage": 1,
    "totalPages": 3,
    "nextPage": 2,
    "prevPage": null
  }
}

Conversation fields

Field	Type	Description
`chatId`	number	Internal chat id — pass it to the messages endpoint.
`contact.id`	number	Internal contact id.
`contact.phone`	string \| null	The contact’s phone (digits).
`contact.name`	string \| null	Display name (CRM full/first name, else the WhatsApp profile name).
`status`	string	`open`, `closed`, or `snoozed`.
`unreadMessages`	number	Unread count on this chat.
`lastMessage`	object \| null	Compact preview of the most recent message: `text`, `direction` (`inbound`/`outbound`), `timestamp`, `timestampIso`.
`createdAt`	string \| null	Chat creation time, ISO-8601.
`updatedAt`	string \| null	Last update time, ISO-8601.

List messages of a conversation

GET https://api.minimo.it/public/v1/whatsapp/conversations/:chatId/messages

Newest first. Only WhatsApp-source messages of a chat owned by your company are returned; an unknown or foreign chatId returns 404.

Query parameters

Parameter	Type	Default	Description
`page`	number	`1`	1-based page number.
`pageSize`	number	`30`	Items per page. Clamped to a maximum of 100.

curl "https://api.minimo.it/public/v1/whatsapp/conversations/1234/messages?page=1&pageSize=30" \
  -H "Authorization: Bearer mn-abc123-xyz789"

Response

{
  "data": [
    {
      "id": 99012,
      "wamid": "wamid.HBgLM...",
      "direction": "inbound",
      "type": "text",
      "text": "Ciao, vorrei informazioni sul contratto",
      "media": null,
      "reaction": null,
      "status": "received",
      "senderName": "Mario Rossi",
      "timestamp": 1760000000,
      "timestampIso": "2025-10-09T07:33:20.000Z"
    }
  ],
  "pagination": {
    "totalRecords": 58,
    "currentPage": 1,
    "totalPages": 2,
    "nextPage": 2,
    "prevPage": null
  }
}

Message fields

Field	Type	Description
`id`	number	Internal, monotonic message id — usable as a cursor.
`wamid`	string \| null	Provider message id, when known.
`direction`	`"inbound"` \| `"outbound"`	`inbound` = from the contact; `outbound` = sent by the business/AI.
`type`	`"text"` \| `"image"` \| `"video"` \| `"audio"` \| `"document"`	Normalized message type.
`text`	string \| null	Human-facing text (body / caption / typed placeholder).
`media`	object \| null	`{ url, type, filename }` when the message carries an attachment, else `null`. Unlike the webhook envelope, stored history exposes a fetchable `url`.
`reaction`	string \| null	The reaction emoji placed on this message, if any.
`status`	string	Delivery status (e.g. `sent`, `received`, `failed`).
`senderName`	string \| null	Display name of the sender at send time.
`timestamp`	number \| null	Message time, epoch seconds.
`timestampIso`	string \| null	Message time, ISO-8601.

Pagination shape

Both endpoints return the same pagination object:

Field	Type	Description
`totalRecords`	number	Total items across all pages.
`currentPage`	number	The page returned.
`totalPages`	number	Total number of pages.
`nextPage`	number \| null	Next page number, or `null` on the last page.
`prevPage`	number \| null	Previous page number, or `null` on the first page.

Inbound Webhook — the real-time push side
Send a Message

Overview

Core Data

Messaging Channels

Connect a Bot (WhatsApp)

Legacy (Deprecated)

Overview

List conversations

Query parameters

Response

Conversation fields

List messages of a conversation

Query parameters

Response

Message fields

​Overview

​List conversations

​Query parameters

​Response

​Conversation fields

​List messages of a conversation

​Query parameters

​Response

​Message fields

​Pagination shape

​Related

Overview

List conversations

Query parameters

Response

Conversation fields

List messages of a conversation

Query parameters

Response

Message fields

Pagination shape

Related