> ## Documentation Index > Fetch the complete documentation index at: https://messages.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # List messages > Returns messages in a chat, ordered by most recent first. Supports cursor-based pagination. ## OpenAPI ````yaml GET /v1/messages openapi: 3.1.0 info: title: Messages.dev API version: '1.0' description: > The Messages.dev API lets you send and receive iMessages programmatically. ## Recommended: use the TypeScript SDK `@messages-dev/sdk` (`npm install @messages-dev/sdk`) is the recommended integration for TypeScript and Node.js. It wraps every endpoint below with a typed client, handles cursor pagination, throws typed errors, and ships `verifyWebhook()` which gets the HMAC scheme right (`HMAC(${timestamp}.${body})` with replay protection). See the [SDK reference](/sdk). The REST API documented here is the underlying transport — use it directly from any language without TypeScript. ## Conventions All endpoints are prefixed with `/v1` and return JSON. Request and response fields use `snake_case`. All IDs include a type prefix (e.g. `msg_`, `cht_`). Write operations (POST /messages, /audio-messages, /reactions, /typing, /receipts) are **asynchronous**. They return a delivery ID with `status: "pending"`. Use `GET /outbox` or webhooks to track delivery. ## Capabilities - Send and receive text messages, with optional file attachments and reply-to threading. - Send native iMessage **audio messages** (waveform balloon) via `POST /v1/audio-messages`. Inbound voice memos arrive on `message.received` with `is_audio_message: true` and include Apple's on-device `transcription`. - Send **iMessage reactions** (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`) via `POST /v1/reactions`. Receive inbound reactions via the `reaction.added` / `reaction.removed` webhooks. - Send **typing indicators** and **read receipts**. - Upload files and send them as attachments (or as **vCard contact cards** — see Recipes). - **Group chats**: send to a `cht_...` chat ID returned by `GET /v1/chats`. - **Webhooks** for `message.received`, `message.sent`, `reaction.added`, `reaction.removed`. Signed with HMAC-SHA256 over `${timestamp}.${body}`. ## Contact-first restriction To protect lines from being flagged as spammers, you can only send to a contact after they have messaged your line first. Attempting to send to a contact that has not messaged in returns `403 contact_has_not_messaged`. The sandbox line is pre-paired with your phone number once you activate it. ## Recipes A few capabilities are compositions of existing endpoints rather than a dedicated route. The SDK wraps each as a single call. | Capability | Mechanism | SDK helper | |---|---|---| | Send a contact card | `POST /v1/files` (`Content-Type: text/vcard`) → `POST /v1/messages` with the returned file ID in `attachments` | `client.sendContactCard()` | | Send a native audio message | `POST /v1/files` (audio mime) → `POST /v1/audio-messages` with the file ID as `audio_message` | `client.sendAudioMessage()` | | Reply to a specific message | `POST /v1/messages` with `reply_to: "msg_..."` (or a raw iMessage GUID) | `replyTo` parameter on every send method | | Send into a group chat | `POST /v1/messages` with a `cht_...` chat ID as `to`. Discover chats via `GET /v1/chats`. | Same `to` parameter | | Test webhooks locally | Build a real signed delivery yourself, then POST it to your handler — `verifyWebhook()` accepts it without a test-mode flag. | `signWebhook` / `buildWebhookDelivery` | servers: - url: https://api.messages.dev description: Messages.dev API security: - BearerAuth: [] tags: - name: Lines description: Your iMessage phone numbers and Apple IDs - name: Chats description: Conversations on a line - name: Messages description: Send and retrieve messages - name: Reactions description: iMessage reactions (love, like, etc.) on messages - name: Typing description: Typing indicators - name: Read Receipts description: Read receipt tracking - name: Delivery description: Track delivery status of write operations - name: Files description: Upload and retrieve file attachments - name: Webhooks description: Real-time event notifications paths: /v1/messages: get: tags: - Messages summary: List messages description: | Returns messages in a chat, ordered by most recent first. Supports cursor-based pagination. operationId: list-messages parameters: - $ref: '#/components/parameters/from' - $ref: '#/components/parameters/to' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' responses: '200': description: List of messages content: application/json: schema: allOf: - $ref: '#/components/schemas/ListResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/Message' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: from: name: from in: query required: true description: Line handle (phone number or Apple ID) schema: type: string example: '+15551234567' to: name: to in: query required: true description: Chat identifier (phone number, Apple ID, or chat ID) schema: type: string example: '+15559876543' limit: name: limit in: query required: false description: 'Maximum number of items to return (1-100, default: 50)' schema: type: integer minimum: 1 maximum: 100 default: 50 cursor: name: cursor in: query required: false description: >- Opaque cursor for pagination. Use the `next_cursor` value from a previous response. schema: type: string schemas: ListResponse: type: object properties: data: type: array items: {} has_more: type: boolean description: Whether more items exist beyond this page next_cursor: type: - string - 'null' description: Cursor to pass as `cursor` query parameter for the next page request_id: type: string Message: type: object properties: id: type: string description: Message ID (e.g. `msg_abc123`) line_id: type: string chat_id: type: string description: Parent chat ID (e.g. `cht_abc123`) guid: type: string description: >- Unique iMessage GUID. Accepted as `message_id` when sending reactions or as `reply_to` when threading replies. sender: type: string description: Sender handle text: type: - string - 'null' description: >- Message text content. `null` when the message is attachment-only (e.g. an audio message or a contact card). attachments: type: array items: type: object properties: filename: type: - string - 'null' mime_type: type: - string - 'null' size: type: - number - 'null' url: type: - string - 'null' description: Download URL for the attachment file transcription: type: - string - 'null' description: > Apple's on-device transcription for inbound voice memos. `null` for non-voice-memo attachments and may be `null` on the first delivery if transcription hasn't finished yet. service: type: - string - 'null' description: '`imessage` or `sms`' is_from_me: type: boolean description: Whether the message was sent by the line owner is_audio_message: type: - boolean - 'null' description: | `true` for native tap-to-record voice memos. The audio file is available in `attachments[0]` along with `transcription`. sent_at: type: number description: Unix timestamp (ms) when the message was sent synced_at: type: number description: Unix timestamp (ms) when the message was synced outbox_id: type: - string - 'null' description: Outbox item ID if sent via API (e.g. `obx_abc123`) reply_to_guid: type: - string - 'null' description: iMessage GUID of the message this is a reply to Error: type: object properties: error: type: object properties: type: type: string description: Error category enum: - authentication_error - authorization_error - invalid_request_error - not_found_error - rate_limit_error code: type: string description: Machine-readable error code message: type: string description: Human-readable error description param: type: string description: The parameter that caused the error, if applicable request_id: type: string description: Unique request identifier for debugging responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: missing_required_parameter message: The 'from' query parameter is required. param: from request_id: req_abc123 Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: missing_api_key message: >- Missing Authorization header. Use 'Authorization: Bearer sk_live_...' request_id: req_abc123 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: not_found_error code: line_not_found message: Line not found. param: from request_id: req_abc123 securitySchemes: BearerAuth: type: http scheme: bearer description: | Use an API key as a bearer token: `Authorization: Bearer sk_live_...` Each key has a set of scopes that gate which endpoints it can call: `messages:read`, `messages:write`, `chats:read`, `lines:read`, `reactions:read`, `reactions:write`, `typing:read`, `typing:write`, `receipts:read`, `receipts:write`, `webhooks:read`, `webhooks:write`, `outbox:read`, `files:read`, `files:write`. Keys can also be restricted to a subset of lines. ````