---
title: "Reply to a conversation"
method: POST
path: "/inbox/conversations/{conversationId}/reply"
tags: ["Inbox"]
---

# Reply to a conversation

`POST /inbox/conversations/{conversationId}/reply`

Sends a reply in an existing conversation (DM, comment, or mention) on Instagram, Facebook, LinkedIn, TikTok (comments only), YouTube (comments only), X (DM-only), or Threads (replies and mentions; needs a Threads connection with the reply permission, else 401 `reauth_required`). You can only reply to conversations that already exist in your inbox — the API cannot start new conversations (Instagram requires the user to message first, and cold outreach violates Meta policy). Direct-message replies must be within the platform's messaging window (24 hours since the user's last message); replies outside the window are rejected. TikTok replies are text-only, capped at 150 characters (400 `validation_error` beyond that), and can take a few minutes to appear on TikTok while they pass spam review. Each workspace can send up to 1,000 replies per rolling 24 hours (429 `reply_limit_reached` beyond that) — contact robert@omnisocials.com if you need a higher limit. X DM replies debit 2 credits from the company balance before the send (auto-refunded if the send fails) and can return 402 `insufficient_credits` or 402 `x_inbox_suspended`. Requires the `inbox:write` scope (API keys) or the `access_social_inbox` permission (OAuth/MCP).

## Path parameters

- `conversationId` string, required

## Request body

- object — Either `text` or `attachment_url` must be set.
  - `text` string — Reply body (max 2000 characters; TikTok comments max 150). Optional when `attachment_url` is set — an attachment-only DM is allowed.
  - `attachment_url` string — Optional media URL to send (Facebook and Instagram DMs only)
  - `attachment_type` 'image' | 'video' | 'audio' | 'file' — Required if attachment_url is set

## Response `200`

Reply sent

- object
  - `data` InboxMessage
    - `id` string
    - `conversation_id` string
    - `platform` string
    - `type` 'dm' | 'comment' | 'mention'
    - `direction` 'incoming' | 'outgoing'
    - `text` string
    - `timestamp` string, date-time
    - `is_read` boolean
    - `is_replied` boolean
    - `reaction` string, nullable
    - `parent_comment_id` string, nullable
    - `hidden` boolean, nullable — Threads replies only: true when the reply is hidden on Threads (see POST /inbox/messages/{id}/hide)
    - `permalink` string, nullable — Link to the reply or mentioning post on the platform, when known
    - `attachment` object, nullable — Media sent with this message, when present. Incoming Instagram/Facebook DM images, videos, voice messages, and story mentions are re-hosted on our CDN so the URL stays valid indefinitely (the platform's own URL is short-lived). `type: file` covers attachment types we could fetch but don't otherwise recognize.
      - `url` string
      - `type` 'image' | 'video' | 'audio' | 'file'
    - `sender` InboxParticipant
      - `id` string — Platform-scoped id of the other party
      - `name` string
      - `username` string
      - `profile_picture` string, nullable
    - `post` object, nullable
      - `id` string, nullable
      - `caption` string, nullable
      - `thumbnail` string, nullable

## Other responses

- `400` — Validation error, `unsupported_platform`, or `unsupported_reply_type` (the conversation's platform/type cannot be replied to, e.g. an Instagram story mention)
- `402` — X DMs only — `insufficient_credits` (balance cannot cover the 2-credit send) or `x_inbox_suspended` (X inbox paused at zero balance; top up and re-enable)
- `403` — Platform limitation (e.g. cannot comment on a personal-profile post)
- `404` — Conversation not found in this workspace
- `422` — Outside the messaging window
- `429` — Daily reply limit reached for this workspace

---

[API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) · [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/omnisocials/omnisocials-api/revisions/e53b89af0b98/schema)