Sign in

v4

OpenAPI 3.0.0MIT2026-07-311554531.6 MB
Agents

Send an agent 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 }.

post/v1/agents/{agentId}/reply

Path parameters

agentIdstring required

Agent identifier (slug) for the agent that owns the conversation.

Request body

conversationIdstring required

Conversation id to reply into. Obtained from the inbound agent event / bridge payload.

integrationIdentifierstring required

Channel integration identifier linked to the agent for this conversation (e.g. slack-support).

errorboolean

Bridge reports that the customer runtime failed this turn. Cannot be combined with other actions. Novu delivers generic user-facing error copy.

Example request

{
  "conversationId": "64f5a1c2e8b7a3d9f0c1b2a3",
  "integrationIdentifier": "slack-support",
  "reply": {
    "markdown": "**Report ready.** Your weekly summary is attached.",
    "files": [
      {
        "filename": "report.pdf",
        "mimeType": "application/pdf",
        "data": "JVBERi0xLjQK...",
        "url": "https://example.com/files/report.pdf"
      }
    ]
  },
  "toolApprovalRequest": {
    "approvalId": "apr_01HZX",
    "toolCallId": "call_refund_1",
    "name": "issue_refund",
    "input": {
      "orderId": "ORD-42",
      "amountCents": 2500
    }
  },
  "edit": {
    "messageId": "1712345678.123456",
    "content": {
      "markdown": "**Report ready.** Your weekly summary is attached.",
      "files": [
        {
          "filename": "report.pdf",
          "mimeType": "application/pdf",
          "data": "JVBERi0xLjQK...",
          "url": "https://example.com/files/report.pdf"
        }
      ]
    }
  },
  "resolve": {
    "summary": "Answered billing question about invoice INV-42."
  },
  "signals": [
    {
      "key": "crm:ticketId"
    }
  ],
  "toolResults": [
    {
      "toolCallId": "call_abc123",
      "toolName": "lookup_order",
      "preview": "Order ORD-42 is shipped"
    }
  ],
  "addReactions": [
    {
      "messageId": "1712345678.123456",
      "emojiName": "white_check_mark"
    }
  ],
  "deleteMessages": [
    {
      "messageId": "1712345678.123456"
    }
  ],
  "typing": {
    "status": "Looking up your order…"
  },
  "error": true
}

Response

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.

messageIdstring required

Platform-native message id of the delivered or edited message (e.g. Slack ts, Teams activity id).

platformThreadIdstring required

Platform-native thread / conversation id where the message was delivered.

Example response

{
  "messageId": "1712345678.123456",
  "platformThreadId": "C0123456789"
}