---
title: "Send an agent reply"
method: POST
path: "/v1/agents/{agentId}/reply"
tags: ["Agents"]
---

# Send an agent reply

`POST /v1/agents/{agentId}/reply`

Send a message or side-effect into an existing agent conversation from your backend.

Use this endpoint when you are not using `@novu/framework` (for example Python, Go, PHP, .NET, or Java SDKs),
or when a server process outside the bridge needs to post into a live conversation.

**Message actions**
- `reply` — markdown, interactive card, or tool-approval card (optional `files`)
- `edit` — update a previously delivered message in place
- `deleteMessages` — remove rendered platform messages (history is kept)
- `addReactions` — add emoji reactions to existing messages

**Turn control**
- `typing` — `{ status?: string }` to set status, or `"stop"` to clear
- `resolve` — mark the conversation resolved (optionally with a final reply)
- `error: true` — report a customer-runtime failure (cannot combine with other actions)

**Signals & tools**
- `signals` — metadata set/delete/clear, or trigger a Novu workflow
- `toolResults` — persist tool outputs into conversation history
- `toolApprovalRequest` — ledger a gated tool call (pair with an approval card reply)

Returns `{ data: { messageId, platformThreadId } }` when a reply or edit is delivered;
otherwise `{ data: null }`.

## Path parameters

- `agentId` string, required

## Request body

- AgentReplyPayloadDto
  - `conversationId` string, required — Conversation id to reply into. Obtained from the inbound agent event / bridge payload.
  - `integrationIdentifier` string, required — Channel integration identifier linked to the agent for this conversation (e.g. `slack-support`).
  - `reply` union — Outbound message content. Exactly one of `markdown`, `card`, or `toolApprovalCard`. Optional `files` attach to the message. Cannot be combined with `edit`.
    - MarkdownReplyContentDto
      - `markdown` string, required — Plain text or markdown body. Converted to the platform-native format by Novu.
      - `files` FileRefDto[] — Optional attachments (max 15). Each file needs exactly one of data or url.
        - `filename` string, required — Filename shown to the end user, including extension.
        - `mimeType` string — IANA MIME type of the file.
        - `data` string — Base64-encoded inline file bytes. Mutually exclusive with `url`. Decoded size must be ≤ 5 MB. Prefer `url` for larger files.
        - `url` string — Publicly accessible HTTP(S) URL. Mutually exclusive with `data`. Server-side limits: 25 MB per file, 15 files per message, 50 MB aggregate.
    - CardReplyContentDto
      - `card` object, required — Interactive card as a Chat SDK element tree (`type: "card"`). Prefer building with `@novu/framework` Card helpers when using TypeScript.
      - `files` FileRefDto[] — Optional attachments (max 15). Supported alongside cards on platforms that allow it (e.g. WhatsApp).
        - `filename` string, required — Filename shown to the end user, including extension.
        - `mimeType` string — IANA MIME type of the file.
        - `data` string — Base64-encoded inline file bytes. Mutually exclusive with `url`. Decoded size must be ≤ 5 MB. Prefer `url` for larger files.
        - `url` string — Publicly accessible HTTP(S) URL. Mutually exclusive with `data`. Server-side limits: 25 MB per file, 15 files per message, 50 MB aggregate.
    - ToolApprovalCardReplyContentDto
      - `toolApprovalCard` object, required — Novu tool-approval card descriptor (`type: "tool-approval-card"`). Used with `toolApprovalRequest` to render Approve/Deny UI.
      - `files` FileRefDto[]
        - `filename` string, required — Filename shown to the end user, including extension.
        - `mimeType` string — IANA MIME type of the file.
        - `data` string — Base64-encoded inline file bytes. Mutually exclusive with `url`. Decoded size must be ≤ 5 MB. Prefer `url` for larger files.
        - `url` string — Publicly accessible HTTP(S) URL. Mutually exclusive with `data`. Server-side limits: 25 MB per file, 15 files per message, 50 MB aggregate.
  - `toolApprovalRequest` ToolApprovalRequestPayloadDto
    - `approvalId` string, required — Unique id for this approval request (matches the AI SDK approvalId).
    - `toolCallId` string, required — Id of the tool call awaiting approval.
    - `name` string, required — Name of the gated tool.
    - `input` object — Tool input the model proposed.
  - `edit` EditPayloadDto
    - `messageId` string, required — Platform message id of the message to edit.
    - `content` union, required — Replacement content. Exactly one of markdown, card, or toolApprovalCard.
      - MarkdownReplyContentDto
        - `markdown` string, required — Plain text or markdown body. Converted to the platform-native format by Novu.
        - `files` FileRefDto[] — Optional attachments (max 15). Each file needs exactly one of data or url.
          - `filename` string, required — Filename shown to the end user, including extension.
          - `mimeType` string — IANA MIME type of the file.
          - `data` string — Base64-encoded inline file bytes. Mutually exclusive with `url`. Decoded size must be ≤ 5 MB. Prefer `url` for larger files.
          - `url` string — Publicly accessible HTTP(S) URL. Mutually exclusive with `data`. Server-side limits: 25 MB per file, 15 files per message, 50 MB aggregate.
      - CardReplyContentDto
        - `card` object, required — Interactive card as a Chat SDK element tree (`type: "card"`). Prefer building with `@novu/framework` Card helpers when using TypeScript.
        - `files` FileRefDto[] — Optional attachments (max 15). Supported alongside cards on platforms that allow it (e.g. WhatsApp).
          - `filename` string, required — Filename shown to the end user, including extension.
          - `mimeType` string — IANA MIME type of the file.
          - `data` string — Base64-encoded inline file bytes. Mutually exclusive with `url`. Decoded size must be ≤ 5 MB. Prefer `url` for larger files.
          - `url` string — Publicly accessible HTTP(S) URL. Mutually exclusive with `data`. Server-side limits: 25 MB per file, 15 files per message, 50 MB aggregate.
      - ToolApprovalCardReplyContentDto
        - `toolApprovalCard` object, required — Novu tool-approval card descriptor (`type: "tool-approval-card"`). Used with `toolApprovalRequest` to render Approve/Deny UI.
        - `files` FileRefDto[]
          - `filename` string, required — Filename shown to the end user, including extension.
          - `mimeType` string — IANA MIME type of the file.
          - `data` string — Base64-encoded inline file bytes. Mutually exclusive with `url`. Decoded size must be ≤ 5 MB. Prefer `url` for larger files.
          - `url` string — Publicly accessible HTTP(S) URL. Mutually exclusive with `data`. Server-side limits: 25 MB per file, 15 files per message, 50 MB aggregate.
  - `resolve` ResolveDto
    - `summary` string — Optional human-readable resolution summary stored on the conversation.
  - `signals` union[] — Side-effect signals executed during this turn: conversation metadata mutations or Novu workflow triggers.
    - union
      - MetadataSetSignalDto
        - `type` 'metadata', required
        - `action` 'set' — Defaults to `set` when omitted.
        - `key` string, required — Metadata key (1–128 chars; letters, digits, and `-` `_` `:` separators).
        - `value` object, required — JSON-serializable value to store.
      - MetadataDeleteSignalDto
        - `type` 'metadata', required
        - `action` 'delete', required
        - `key` string, required — Metadata key to remove.
      - MetadataClearSignalDto
        - `type` 'metadata', required
        - `action` 'clear', required
      - TriggerSignalDto
        - `type` 'trigger', required
        - `workflowId` string, required — Workflow identifier (same string used with `events.trigger`).
        - `to` union — Recipient(s). Accepts a subscriberId string, subscriber object, topic object, or an array of those. When omitted, Novu falls back to the conversation subscriber.
          - string
          - object
          - union[]
            - union
              - …
        - `payload` object — Arbitrary payload forwarded to the workflow.
  - `toolResults` ToolResultDto[] — Tool-call outcomes to persist in conversation history (typically before the assistant reply).
    - `toolCallId` string, required — Id of the tool call this result resolves.
    - `toolName` string — Name of the tool that produced this result.
    - `output` object — JSON-serializable tool output (or the execution-denied marker).
    - `preview` string — Human-readable preview for the display timeline.
  - `addReactions` AddReactionPayloadDto[] — Emoji reactions to add to existing platform messages.
    - `messageId` string, required — Platform message id to react to.
    - `emojiName` string, required — Well-known cross-platform emoji name (e.g. `white_check_mark`, `thumbsup`).
  - `deleteMessages` DeleteMessagePayloadDto[] — Delete previously posted platform messages. Removes the rendered message only — history is preserved.
    - `messageId` string, required — Platform message id to delete. Removes the rendered message only — history is preserved.
  - `typing` union — Per-turn typing/status control. Pass `{ status?: string }` to set/update the status (omit `status` for "Thinking…"), or `"stop"` to clear it. Best-effort per platform.
    - 'stop' — Clear the typing indicator.
    - TypingStatusDto
      - `status` string — Status text shown while the agent works. Omit for the default "Thinking…".
  - `error` boolean — Bridge reports that the customer runtime failed this turn. Cannot be combined with other actions. Novu delivers generic user-facing error copy.

## Response `200`

OK. When a reply or edit is delivered, `data` contains the platform message identifiers. Side-effect-only requests (typing, reactions, deletes, signals without an outbound message) return `data: null`.

- SentMessageInfoDto
  - `messageId` string, required — Platform-native message id of the delivered or edited message (e.g. Slack `ts`, Teams activity id).
  - `platformThreadId` string, required — Platform-native thread / conversation id where the message was delivered.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — The agent or conversation was not found.
- `405` — Method Not Allowed
- `409` — Conflict
- `413` — Payload Too Large
- `414` — URI Too Long
- `415` — Unsupported Media Type
- `422` — Unprocessable Entity
- `429` — The client has sent too many requests in a given amount of time.
- `500` — Internal Server Error
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

---

[API](https://skmtc.net/novu/apis/deprecated-novu-api-use-openapi-json-yaml-instead.md) · [All operations](https://skmtc.net/novu/apis/deprecated-novu-api-use-openapi-json-yaml-instead/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/novu/deprecated-novu-api-use-openapi-json-yaml-instead/versions/986fe259fa85/schema)