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

# REST API endpoints for conversations — Waply API

> List, read, assign, resolve, and add internal notes to conversations using the Waply conversations REST API. Includes the Conversation object schema.

Conversations in Waply represent the thread of messages between you and a contact on a particular channel. Each conversation has a status, an optional assignee, and a log of all messages exchanged. Use the conversations API to build custom inboxes, automate triage, or integrate Waply into your support tooling.

## The Conversation object

<ResponseField name="id" type="string">
  Unique identifier for the conversation, prefixed with `conv_`.
</ResponseField>

<ResponseField name="contact_id" type="string">
  ID of the contact this conversation is with.
</ResponseField>

<ResponseField name="channel" type="string">
  The messaging channel. One of `whatsapp`, `instagram`, `messenger`, or `webchat`.
</ResponseField>

<ResponseField name="status" type="string">
  Current conversation status. One of `open` or `resolved`.
</ResponseField>

<ResponseField name="assigned_to" type="object">
  The agent or team the conversation is assigned to, or `null` if unassigned.

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      Either `user` or `team`.
    </ResponseField>

    <ResponseField name="id" type="string">
      ID of the assigned user or team.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the assigned user or team.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="messages" type="object[]">
  Array of Message objects in the conversation, ordered oldest-first. See the [Messages reference](/api-reference/messages) for the Message object schema.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the conversation was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent activity in the conversation.
</ResponseField>

***

## List conversations

### GET /conversations

Returns a paginated list of conversations. Filter by status, channel, or assigned agent.

<ParamField query="status" type="string" default="open">
  Filter by conversation status. One of `open`, `resolved`, or `all`.
</ParamField>

<ParamField query="channel" type="string">
  Filter by channel. One of `whatsapp`, `instagram`, `messenger`, or `webchat`.
</ParamField>

<ParamField query="assigned_to" type="string">
  Filter by the ID of the user the conversation is assigned to.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number to retrieve.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of conversations per page. Maximum is `100`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.waply.io/v1/conversations?status=open&channel=whatsapp&limit=20' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    status: 'open',
    channel: 'whatsapp',
    limit: 20,
  });
  const response = await fetch(`https://api.waply.io/v1/conversations?${params}`, {
    headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
  });
  const { data, total, page } = await response.json();
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.get(
      'https://api.waply.io/v1/conversations',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
      params={'status': 'open', 'channel': 'whatsapp', 'limit': 20},
  )
  result = response.json()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "data": [
    {
      "id": "conv_01HABC",
      "contact_id": "con_01HXYZ",
      "channel": "whatsapp",
      "status": "open",
      "assigned_to": {
        "type": "user",
        "id": "usr_01H111",
        "name": "Alice Support"
      },
      "messages": [],
      "created_at": "2026-04-15T08:30:00Z",
      "updated_at": "2026-04-16T09:12:00Z"
    }
  ],
  "total": 38,
  "page": 1
}
```

***

## Get a conversation

### GET /conversations/{id}

Returns a single conversation including its full message history.

<ParamField path="id" type="string" required>
  The ID of the conversation to retrieve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.waply.io/v1/conversations/conv_01HABC \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.waply.io/v1/conversations/conv_01HABC', {
    headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
  });
  const conversation = await response.json();
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.get(
      'https://api.waply.io/v1/conversations/conv_01HABC',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
  )
  conversation = response.json()
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "id": "conv_01HABC",
  "contact_id": "con_01HXYZ",
  "channel": "whatsapp",
  "status": "open",
  "assigned_to": null,
  "messages": [
    {
      "id": "msg_01HMNO",
      "conversation_id": "conv_01HABC",
      "direction": "inbound",
      "type": "text",
      "content": "Hello, I need help with my order.",
      "status": "delivered",
      "created_at": "2026-04-16T09:10:00Z"
    }
  ],
  "created_at": "2026-04-16T09:10:00Z",
  "updated_at": "2026-04-16T09:10:00Z"
}
```

***

## Assign a conversation

### POST /conversations/{id}/assign

Assigns a conversation to a specific agent or team. Provide either `user_id` or `team_id`, not both.

<ParamField path="id" type="string" required>
  The ID of the conversation to assign.
</ParamField>

<ParamField body="user_id" type="string">
  ID of the user to assign the conversation to.
</ParamField>

<ParamField body="team_id" type="string">
  ID of the team to assign the conversation to.
</ParamField>

<CodeGroup>
  ```bash cURL — assign to user theme={null}
  curl --request POST \
    --url https://api.waply.io/v1/conversations/conv_01HABC/assign \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{"user_id": "usr_01H111"}'
  ```

  ```bash cURL — assign to team theme={null}
  curl --request POST \
    --url https://api.waply.io/v1/conversations/conv_01HABC/assign \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{"team_id": "team_01H222"}'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://api.waply.io/v1/conversations/conv_01HABC/assign', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ user_id: 'usr_01H111' }),
  });
  ```

  ```python Python theme={null}
  import requests, os

  requests.post(
      'https://api.waply.io/v1/conversations/conv_01HABC/assign',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
      json={'user_id': 'usr_01H111'},
  )
  ```
</CodeGroup>

**Response**

Returns the updated Conversation object with `assigned_to` populated.

```json theme={null}
{
  "id": "conv_01HABC",
  "contact_id": "con_01HXYZ",
  "channel": "whatsapp",
  "status": "open",
  "assigned_to": {
    "type": "user",
    "id": "usr_01H111",
    "name": "Alice Support"
  },
  "messages": [],
  "created_at": "2026-04-16T09:10:00Z",
  "updated_at": "2026-04-16T10:00:00Z"
}
```

***

## Resolve a conversation

### POST /conversations/{id}/resolve

Marks a conversation as resolved. Resolved conversations no longer appear in the default open inbox view. You can reopen a resolved conversation by assigning or replying to it.

<ParamField path="id" type="string" required>
  The ID of the conversation to resolve.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.waply.io/v1/conversations/conv_01HABC/resolve \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://api.waply.io/v1/conversations/conv_01HABC/resolve', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
  });
  ```

  ```python Python theme={null}
  import requests, os

  requests.post(
      'https://api.waply.io/v1/conversations/conv_01HABC/resolve',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
  )
  ```
</CodeGroup>

**Response**

Returns the updated Conversation object with `status` set to `resolved`.

```json theme={null}
{
  "id": "conv_01HABC",
  "contact_id": "con_01HXYZ",
  "channel": "whatsapp",
  "status": "resolved",
  "assigned_to": null,
  "messages": [],
  "created_at": "2026-04-16T09:10:00Z",
  "updated_at": "2026-04-16T10:15:00Z"
}
```

***

## Add an internal note

### POST /conversations/{id}/notes

Adds an internal note to a conversation. Notes are only visible to your team — they are never sent to the contact.

<ParamField path="id" type="string" required>
  The ID of the conversation to add a note to.
</ParamField>

<ParamField body="content" type="string" required>
  The text content of the internal note.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.waply.io/v1/conversations/conv_01HABC/notes \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{"content": "Customer is on the Enterprise plan. Check their Salesforce record before responding."}'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://api.waply.io/v1/conversations/conv_01HABC/notes', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: 'Customer is on the Enterprise plan. Check their Salesforce record before responding.',
    }),
  });
  ```

  ```python Python theme={null}
  import requests, os

  requests.post(
      'https://api.waply.io/v1/conversations/conv_01HABC/notes',
      headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
      json={'content': 'Customer is on the Enterprise plan. Check their Salesforce record before responding.'},
  )
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "id": "note_01HPQR",
  "conversation_id": "conv_01HABC",
  "content": "Customer is on the Enterprise plan. Check their Salesforce record before responding.",
  "created_at": "2026-04-16T10:20:00Z"
}
```