> For the complete documentation index, see [llms.txt](https://help.contouron.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.contouron.com/api/messages.md).

# Messages

> For the complete documentation index, see [llms.txt](https://help.contouron.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.contouron.com/api/messages.md).

## Messages

Contouron allows you to read and send direct messages on your Instagram account. Twitter/X, TikTok, Pinterest, Threads, Bluesky, and YouTube are not supported at this time. Five endpoints let you list conversations, read a conversation, list messages, read a message, and send a message:

* [List Conversations](#list-conversations) — `GET /v2/conversations`
* [Get Conversation](#get-conversation) — `GET /v2/conversations/:conversationId`
* [List Messages](#list-messages) — `GET /v2/messages`
* [Get Message](#get-message) — `GET /v2/messages/:messageId`
* [Send Message](#send-message) — `POST /v2/messages`

Each message has a `direction`:

* **Incoming messages** your contacts send you. These have `direction: "incoming"`.
* **Outgoing messages** you send through Contouron. These have `direction: "outgoing"`.

You reply to people who already have a conversation with you. You send to a `recipientId` taken from an existing conversation or an incoming message, not to an arbitrary user. The social platform limits who you can message and when. See [Messaging Windows](#messaging-windows).

Contouron retains messages for up to 45 days. Messages older than 45 days are not available through these endpoints.

### Before You Start

Contouron must have permissions to read and send messages on your account before you can use the Contouron messaging endpoints.

If you connected your account before messaging launched, reconnect it so Contouron has the new permission.

* For Instagram, see Connect Instagram.

***

### List Conversations

#### Endpoint

**Base URL:** `https://backend.contouron.com/v2`

**URL:** `/conversations`

**Method:** `GET`

#### Description

Returns your conversations across connected accounts, ordered by most recent activity. Use cursor-based pagination and the optional filters below.

#### Query Parameters

| Field       | Type      | Required | Description                                                      |
| ----------- | --------- | -------- | ---------------------------------------------------------------- |
| `limit`     | `integer` | No       | Maximum conversations to return (1-250). Default 50.             |
| `cursor`    | `string`  | No       | Cursor from a previous response. Pass it to fetch the next page. |
| `platform`  | `string`  | No       | Filter by platform. Value: `instagram`.                          |
| `accountId` | `string`  | No       | Filter to a single connected account.                            |

#### Response

**Status Code:** `200 OK`

```json
{
  "items": [
    {
      "id": "cnv_abc123",
      "accountId": "98434",
      "platform": "instagram",
      "participants": [
        {
          "id": "1784000000",
          "name": "Jamie Rivera",
          "username": "jamie.rivera",
          "profileImageUrl": "https://example.com/avatar.jpg"
        }
      ],
      "createdAt": "2026-07-01T12:00:00Z",
      "updatedAt": "2026-07-02T09:30:00Z"
    }
  ],
  "cursor": "eyJz..."
}
```

| Field    | Type     | Description                                                             |
| -------- | -------- | ----------------------------------------------------------------------- |
| `items`  | `array`  | List of conversations. See [Conversation Object](#conversation-object). |
| `cursor` | `string` | Cursor for the next page. Absent when there are no more conversations.  |

***

### Get Conversation

#### Endpoint

**URL:** `/conversations/:conversationId`

**Method:** `GET`

#### Description

Fetches a single conversation by its Contouron ID.

#### Path Parameters

| Field            | Type     | Required | Description                       |
| ---------------- | -------- | -------- | --------------------------------- |
| `conversationId` | `string` | Yes      | Contouron ID of the conversation. |

#### Response

**Status Code:** `200 OK`

Returns a [Conversation Object](#conversation-object).

***

### List Messages

#### Endpoint

**URL:** `/messages`

**Method:** `GET`

#### Description

Returns your messages across connected accounts, ordered by creation time (most recent first). Use cursor-based pagination and the optional filters below.

#### Query Parameters

| Field            | Type      | Required | Description                                                      |
| ---------------- | --------- | -------- | ---------------------------------------------------------------- |
| `limit`          | `integer` | No       | Maximum messages to return (1-250). Default 50.                  |
| `cursor`         | `string`  | No       | Cursor from a previous response. Pass it to fetch the next page. |
| `conversationId` | `string`  | No       | Filter to messages in a single conversation.                     |
| `platform`       | `array`   | No       | Filter by platform. Value: `instagram`.                          |
| `accountId`      | `string`  | No       | Filter to a single connected account.                            |

#### Response

**Status Code:** `200 OK`

```json
{
  "items": [
    {
      "id": "msg_abc123",
      "conversationId": "cnv_abc123",
      "platform": "instagram",
      "direction": "incoming",
      "senderId": "1784000000",
      "recipientId": "17841400000000000",
      "text": "Hi! Is this still available?",
      "status": "delivered",
      "errorCode": null,
      "errorMessage": null,
      "createdAt": "2026-07-02T09:30:00Z"
    }
  ],
  "cursor": "eyJz..."
}
```

| Field    | Type     | Description                                                       |
| -------- | -------- | ----------------------------------------------------------------- |
| `items`  | `array`  | List of messages. See [Message Object](#message-object).          |
| `cursor` | `string` | Cursor for the next page. Absent when there are no more messages. |

***

### Get Message

#### Endpoint

**URL:** `/messages/:messageId`

**Method:** `GET`

#### Description

Fetches a single message by its Contouron ID. Poll this after [Send Message](#send-message) to check whether an outgoing message reached `sent` or `failed`.

#### Path Parameters

| Field       | Type     | Required | Description                  |
| ----------- | -------- | -------- | ---------------------------- |
| `messageId` | `string` | Yes      | Contouron ID of the message. |

#### Response

**Status Code:** `200 OK`

Returns a [Message Object](#message-object).

***

### Send Message

#### Endpoint

**URL:** `/messages`

**Method:** `POST`

#### Description

Sends a direct message to one recipient. Contouron queues the message and sends it in the background, so the response returns status `queued`. Poll [Get Message](#get-message) with the returned `id` to confirm the message reached `sent` or `failed`.

Send to a `recipientId` taken from an existing conversation or an incoming message. The social platform limits who you can message and when. See [Messaging Windows](#messaging-windows).

#### Request Body

```json
{
  "accountId": "98434",
  "recipientId": "1784000000",
  "text": "Thanks for reaching out! Yes, it's available.",
  "target": {
    "targetType": "instagram"
  }
}
```

| Field         | Type     | Required | Description                                                                                                     |
| ------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `accountId`   | `string` | Yes      | Contouron ID of the connected account the message is sent from.                                                 |
| `recipientId` | `string` | Yes      | Social platform (e.g. Instagram) ID of the recipient. Get it from an existing conversation or incoming message. |
| `text`        | `string` | Yes      | Plain-text message body. Instagram messages are limited to 1000 bytes.                                          |
| `target`      | `object` | Yes      | Where and how to send. See [Target](#target).                                                                   |

#### Target

| Field          | Type     | Required | Description                                                                                                                                                    |
| -------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetType`   | `string` | Yes      | Value: `instagram`.                                                                                                                                            |
| `commentId`    | `string` | No       | Contouron comment ID. When set, Contouron delivers the message as a private reply to that comment instead of a direct message.                                 |
| `responseType` | `string` | No       | How the message fits the platform's messaging window: `RESPONSE`, `UPDATE`, or `MESSAGE_TAG`. Default `RESPONSE`. See [Messaging Windows](#messaging-windows). |
| `tag`          | `string` | No       | Required when `responseType` is `MESSAGE_TAG` (e.g. `HUMAN_AGENT`).                                                                                            |

#### Response

**Status Code:** `201 Created`

Returns a [Message Object](#message-object) with status `queued`.

#### Errors

| Status | Reason                                                                                                                                                                                                                     |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404`  | The connected account was not found, or messaging is not enabled for your account.                                                                                                                                         |
| `422`  | The message exceeds the platform's character limit, the messaging window has closed, the comment you are replying to is invalid, your connected account expired, or you reached your plan's monthly active-contacts limit. |
| `429`  | Rate limit exceeded (30 requests per minute).                                                                                                                                                                              |

Message-send failures that happen after the message is queued do not return an error here. The message reaches status `failed` with an `errorCode` and `errorMessage`. See Messaging Errors.

***

### Messaging Windows

The social platform limits who you can message and when. You reply to people who already have a conversation with you, not arbitrary users.

* **Standard window:** send a `RESPONSE` within 24 hours of the contact's last message.
* **Private reply to a comment:** set `commentId` on the target to reply once, within 7 days of the comment.
* **Outside the window:** set `responseType` to `MESSAGE_TAG` with an approved `tag` (e.g. `HUMAN_AGENT`) to send a permitted follow-up.

These windows come from the social platform, not Contouron. A message sent outside an allowed window reaches status `failed`.

Sending a message to a new person also counts toward your plan's monthly active-contacts limit. See Active Contacts.

***

### Conversation Object

| Field          | Type     | Description                                                                                                                 |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `string` | Contouron conversation ID.                                                                                                  |
| `accountId`    | `string` | ID of the connected account this conversation belongs to.                                                                   |
| `platform`     | `string` | `instagram`.                                                                                                                |
| `participants` | `array`  | The other people in the conversation. Each has `id`, `name`, `username`, and `profileImageUrl`, any of which may be `null`. |
| `createdAt`    | `string` | ISO 8601 timestamp when the conversation started.                                                                           |
| `updatedAt`    | `string` | ISO 8601 timestamp of the most recent activity.                                                                             |

***

### Message Object

| Field            | Type              | Description                                                            |
| ---------------- | ----------------- | ---------------------------------------------------------------------- |
| `id`             | `string`          | Contouron message ID.                                                  |
| `conversationId` | `string or null`  | Contouron ID of the parent conversation.                               |
| `platform`       | `string`          | `instagram`.                                                           |
| `direction`      | `string`          | `incoming` for messages you receive, `outgoing` for messages you send. |
| `senderId`       | `string or null`  | Social platform (e.g. Instagram) ID of the sender.                     |
| `recipientId`    | `string`          | Social platform (e.g. Instagram) ID of the recipient.                  |
| `text`           | `string`          | Message text.                                                          |
| `status`         | `string`          | Message status. See [Status Values](#status-values).                   |
| `errorCode`      | `integer or null` | Set only when status is `failed`. See Messaging Errors.                |
| `errorMessage`   | `string or null`  | Set only when status is `failed`.                                      |
| `createdAt`      | `string`          | ISO 8601 timestamp when the message was created.                       |

#### Status Values

An outgoing message you send moves through `queued`, `processing`, then `sent`, or `failed` if it does not go through. An incoming message you receive shows as `delivered`.

| Status       | Meaning                               |
| ------------ | ------------------------------------- |
| `queued`     | Accepted and waiting to send.         |
| `processing` | Sending to the social platform.       |
| `sent`       | Handed to the social platform.        |
| `delivered`  | An incoming message delivered to you. |
| `failed`     | Did not send. See `errorMessage`.     |

#### Rate Limits

| Endpoint                             | Limit    |
| ------------------------------------ | -------- |
| `GET /conversations`                 | 60 / min |
| `GET /conversations/:conversationId` | 60 / min |
| `GET /messages`                      | 60 / min |
| `GET /messages/:messageId`           | 60 / min |
| `POST /messages`                     | 30 / min |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.contouron.com/api/messages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.