> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimo.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Read API

> Page through WhatsApp conversations and their message history

## 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**. |

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

### Response

```json theme={null}
{
  "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**. |

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

### Response

```json theme={null}
{
  "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. |

## Related

* [Inbound Webhook](/api-reference/whatsapp-transport/webhooks) — the real-time push side
* [Send a Message](/api-reference/whatsapp-transport/send)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.