# Messages

> Conversations between buyers, sellers and the marketplace.

Conversations between buyers, sellers and the marketplace. Generated from the [OpenAPI spec](https://dev.mongrl.com/openapi.json). Each endpoint says which key it needs; see [Authentication](https://dev.mongrl.com/guides/authentication.md).

| Method | Path | What it does |
|---|---|---|
| GET | [`/v1/me/conversations`](#the-signed-in-users-conversations) | The signed-in user's conversations |
| POST | [`/v1/me/conversations`](#message-the-seller-the-buyer-or-the-marketplace) | Message the seller, the buyer or the marketplace |
| GET | [`/v1/me/conversations/{id}/messages`](#read-a-conversation) | Read a conversation |
| POST | [`/v1/me/conversations/{id}/messages`](#reply-in-a-conversation) | Reply in a conversation |

## The signed-in user's conversations

`GET /v1/me/conversations` · operation `listMyConversations`

Latest first, with the last message and how many are unread.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `limit` | query | integer | ≥ 1; ≤ 100; default `50` |
| `offset` | query | integer | ≥ 0 |

**Responses:** `200` [ConversationListOutputBody](#conversationlistoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Message the seller, the buyer or the marketplace

`POST /v1/me/conversations` · operation `startConversation`

About a listing (a question before buying), an order (its buyer or seller), or support (the marketplace). Continues the existing conversation if there is one.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Body** (`application/json`): [StartConversationRequest](#startconversationrequest)

**Responses:** `201` [StartConversationResponse](#startconversationresponse) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Read a conversation

`GET /v1/me/conversations/{id}/messages` · operation `readMyConversation`

Oldest first; marks them read.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |
| `after` | query | integer | Only messages after this id. ≥ 0 |
| `limit` | query | integer | ≥ 1; ≤ 200; default `100` |

**Responses:** `200` [MessagesOutputBody](#messagesoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Reply in a conversation

`POST /v1/me/conversations/{id}/messages` · operation `sendMessage`

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`application/json`): [MessageInput](#messageinput)

**Responses:** `201` [MessageBody](#messagebody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Schemas

Fields marked * are always present in responses and required in requests.

### ConversationListOutputBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [ConversationBody](#conversationbody)[] |  |

### StartConversationRequest

| Field | Type | Notes |
|---|---|---|
| `body` * | string | max 5000 chars |
| `listing_id` | string |  |
| `order_id` | string |  |
| `support` | boolean | To the marketplace |

### StartConversationResponse

| Field | Type | Notes |
|---|---|---|
| `conversation` * | [ConversationBody](#conversationbody) |  |
| `message` * | [MessageBody](#messagebody) |  |

### MessagesOutputBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [MessageBody](#messagebody)[] |  |

### MessageInput

| Field | Type | Notes |
|---|---|---|
| `body` * | string | max 5000 chars |

### MessageBody

| Field | Type | Notes |
|---|---|---|
| `at` * | string (date-time) |  |
| `body` * | string |  |
| `from_marketplace` * | boolean | Written by the marketplace (support) |
| `id` * | integer |  |
| `sender_id` | string | The user who wrote it |

### ConversationBody

| Field | Type | Notes |
|---|---|---|
| `id` * | string |  |
| `kind` * | string | one of `listing`, `order`, `support` |
| `last_message` | string |  |
| `last_message_at` * | string (date-time) |  |
| `listing_id` | string |  |
| `order_id` | string |  |
| `unread` * | integer |  |
| `user_a` * | string | The buyer, or the user asking for support |
| `user_b` | string | The seller (not in support conversations) |