---
title: "List DM conversations"
method: GET
path: "/conversations"
tags: ["Conversations"]
---

# List DM conversations

`GET /conversations`

## Request

- Base URL: `https://api.postplanify.com/api/v1`
- URL: `https://api.postplanify.com/api/v1/conversations`
- Auth: HTTP bearer

Returns a paginated list of direct message conversations from the workspace's connected **Instagram and Facebook** accounts, newest first (by last message).

Conversations that only contain story mentions are left out. Use `needsReply=true` to get the conversations waiting on an answer.

## Subscription

This endpoint requires the workspace owner to have an active Growth, Premium, or Scale subscription.

## Query parameters

- `workspaceId` string, uuid, required
- `needsReply` boolean
- `unreadOnly` boolean
- `socialAccountId` string, uuid
- `assignedToUserId` string, uuid
- `search` string
- `page` integer
- `limit` integer

## Response `200`

Paginated list of conversations

- object
  - `ok` boolean
  - `data` Conversation[]
    - `id` string, uuid: Conversation ID. Use it in the other `/conversations` endpoints.
    - `workspaceId` string, uuid
    - `participant` object: The customer on the other side of the conversation.
      - `id` string: Platform-scoped user ID (Instagram IGSID or Facebook PSID).
      - `name` string, nullable
      - `username` string, nullable: Instagram handle. Always `null` for Facebook, which does not share one.
      - `profilePictureUrl` string, nullable
    - `lastMessagePreview` string, nullable
    - `lastMessageAt` string, date-time, nullable
    - `lastCustomerMessageAt` string, date-time, nullable: When the customer last wrote. The 24-hour reply window counts from this time.
    - `messageCount` integer
    - `isRead` boolean: Internal read state in PostPlanify. Not shown to the customer.
    - `needsReply` boolean: True when the latest message is from the customer and nobody has answered yet.
    - `replyWindow` object: Instagram and Facebook only allow a business to reply within 24 hours of the customer's last message. Check `canReply` before sending.
      - `canReply` boolean
      - `expiresAt` string, date-time, nullable: When the window closes, or `null` if it is already closed.
    - `label` object, nullable: The inbox label set on this conversation in PostPlanify.
      - `id` string, uuid
      - `name` string
      - `color` string
    - `assignedTo` object, nullable: The teammate this conversation is assigned to.
      - `id` string, uuid
      - `fullName` string, nullable
    - `socialAccount` object, nullable
      - `id` string, uuid
      - `platform` 'INSTAGRAM' | 'FACEBOOK'
      - `accountName` string
      - `profilePictureUrl` string, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `pagination` Pagination
    - `page` integer
    - `limit` integer
    - `total` integer
    - `has_more` boolean

## Other responses

- `400`: Missing workspaceId
- `403`: Workspace requires an active Growth, Premium, or Scale subscription
- `404`: Workspace not found

---

[API](https://skmtc.dev/postplanify/apis/postplanify-api.md) · [All operations](https://skmtc.dev/postplanify/apis/postplanify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postplanify/apis/postplanify-api/revisions/9eae5f1faa56?raw)