Runtime

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

agents

{agentId}

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.agents.sendReply({
    conversationId: "64f5a1c2e8b7a3d9f0c1b2a3",
    integrationIdentifier: "slack-support",
    reply: {
      markdown: "**Report ready.** Your weekly summary is attached.",
    },
  }, "support-agent");

  console.log(result);
}

run();

curl --request POST \
  --url https://api.novu.co/v1/agents/{agentId}/reply \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversationId": "64f5a1c2e8b7a3d9f0c1b2a3",
  "integrationIdentifier": "slack-support",
  "reply": {
    "markdown": "**Report ready.** Your weekly summary is attached."
  }
}
'

import requests

url = "https://api.novu.co/v1/agents/{agentId}/reply"

payload = {
    "conversationId": "64f5a1c2e8b7a3d9f0c1b2a3",
    "integrationIdentifier": "slack-support",
    "reply": { "markdown": "**Report ready.** Your weekly summary is attached." }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    conversationId: '64f5a1c2e8b7a3d9f0c1b2a3',
    integrationIdentifier: 'slack-support',
    reply: {markdown: '**Report ready.** Your weekly summary is attached.'}
  })
};

fetch('https://api.novu.co/v1/agents/{agentId}/reply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novu.co/v1/agents/{agentId}/reply",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'conversationId' => '64f5a1c2e8b7a3d9f0c1b2a3',
    'integrationIdentifier' => 'slack-support',
    'reply' => [
        'markdown' => '**Report ready.** Your weekly summary is attached.'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novu.co/v1/agents/{agentId}/reply"

	payload := strings.NewReader("{\n  \"conversationId\": \"64f5a1c2e8b7a3d9f0c1b2a3\",\n  \"integrationIdentifier\": \"slack-support\",\n  \"reply\": {\n    \"markdown\": \"**Report ready.** Your weekly summary is attached.\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/agents/{agentId}/reply")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"conversationId\": \"64f5a1c2e8b7a3d9f0c1b2a3\",\n  \"integrationIdentifier\": \"slack-support\",\n  \"reply\": {\n    \"markdown\": \"**Report ready.** Your weekly summary is attached.\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/agents/{agentId}/reply")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"conversationId\": \"64f5a1c2e8b7a3d9f0c1b2a3\",\n  \"integrationIdentifier\": \"slack-support\",\n  \"reply\": {\n    \"markdown\": \"**Report ready.** Your weekly summary is attached.\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Send a reply into an existing agent conversation from server-side code. Use this when you are not running @novu/framework on the bridge (for example with the Python, Go, PHP, .NET, or Java SDKs), or when another backend service needs to post into a live conversation. The request body is a bag of optional actions. Provide at least one of reply, edit, resolve, signals, toolResults, toolApprovalRequest, addReactions, deleteMessages, typing, or error. Named examples in the OpenAPI spec cover the common shapes. When a reply or edit is delivered, the response data contains messageId and platformThreadId. Side-effect-only requests return data: null. For the TypeScript bridge API (ctx.reply, cards, signals), see Reply.

Authorizations

Authorization

string

header

required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

idempotency-key

string

A header for idempotency purposes

Path Parameters

agentId

string

required

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

Body

application/json

Reply payload. Provide at least one action: reply, edit, resolve, signals, toolResults, toolApprovalRequest, addReactions, deleteMessages, typing, or error. See named examples for common shapes used by server-side SDKs.

conversationId

string

required

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

Example:

"64f5a1c2e8b7a3d9f0c1b2a3"

integrationIdentifier

string

required

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

Example:

"slack-support"

object

Outbound message content. Exactly one of markdown, card, or toolApprovalCard. Optional files attach to the message. Cannot be combined with edit.

Option 1
Option 2
Option 3

Show child attributes

toolApprovalRequest

object

Tool-lifecycle ledger row for a gated tool call. Pair with reply.toolApprovalCard (or another reply shape) to deliver the approval UI.

Show child attributes

edit

object

In-place edit of a previously posted agent message. Cannot be combined with reply, resolve, signals, toolResults, toolApprovalRequest, addReactions, or deleteMessages.

Show child attributes

resolve

object

Mark the conversation resolved. May be combined with a final reply.

Show child attributes

signals

object[]

Side-effect signals executed during this turn: conversation metadata mutations or Novu workflow triggers.

Option 1
Option 2
Option 3
Option 4

Show child attributes

toolResults

object[]

Tool-call outcomes to persist in conversation history (typically before the assistant reply).

Show child attributes

addReactions

object[]

Emoji reactions to add to existing platform messages.

Show child attributes

deleteMessages

object[]

Delete previously posted platform messages. Removes the rendered message only — history is preserved.

Show child attributes

typing

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.

Available options:

stop

Example:

{ "status": "Looking up your order…" }

error

boolean

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

Example:

true

Response

object | null

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.

messageId

string

required

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

Example:

"1712345678.123456"

platformThreadId

string

required

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

Example:

"C0123456789"

Update an agent bridge

Create an agent integration

⌘I

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.agents.sendReply({
    conversationId: "64f5a1c2e8b7a3d9f0c1b2a3",
    integrationIdentifier: "slack-support",
    reply: {
      markdown: "**Report ready.** Your weekly summary is attached.",
    },
  }, "support-agent");

  console.log(result);
}

run();

curl --request POST \
  --url https://api.novu.co/v1/agents/{agentId}/reply \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversationId": "64f5a1c2e8b7a3d9f0c1b2a3",
  "integrationIdentifier": "slack-support",
  "reply": {
    "markdown": "**Report ready.** Your weekly summary is attached."
  }
}
'

import requests

url = "https://api.novu.co/v1/agents/{agentId}/reply"

payload = {
    "conversationId": "64f5a1c2e8b7a3d9f0c1b2a3",
    "integrationIdentifier": "slack-support",
    "reply": { "markdown": "**Report ready.** Your weekly summary is attached." }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    conversationId: '64f5a1c2e8b7a3d9f0c1b2a3',
    integrationIdentifier: 'slack-support',
    reply: {markdown: '**Report ready.** Your weekly summary is attached.'}
  })
};

fetch('https://api.novu.co/v1/agents/{agentId}/reply', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.novu.co/v1/agents/{agentId}/reply",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'conversationId' => '64f5a1c2e8b7a3d9f0c1b2a3',
    'integrationIdentifier' => 'slack-support',
    'reply' => [
        'markdown' => '**Report ready.** Your weekly summary is attached.'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.novu.co/v1/agents/{agentId}/reply"

	payload := strings.NewReader("{\n  \"conversationId\": \"64f5a1c2e8b7a3d9f0c1b2a3\",\n  \"integrationIdentifier\": \"slack-support\",\n  \"reply\": {\n    \"markdown\": \"**Report ready.** Your weekly summary is attached.\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/agents/{agentId}/reply")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"conversationId\": \"64f5a1c2e8b7a3d9f0c1b2a3\",\n  \"integrationIdentifier\": \"slack-support\",\n  \"reply\": {\n    \"markdown\": \"**Report ready.** Your weekly summary is attached.\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/agents/{agentId}/reply")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"conversationId\": \"64f5a1c2e8b7a3d9f0c1b2a3\",\n  \"integrationIdentifier\": \"slack-support\",\n  \"reply\": {\n    \"markdown\": \"**Report ready.** Your weekly summary is attached.\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Getting Started

Notification delivery

Agents

Data

Workflows & content

Platform & channels

Send an agent reply

Authorizations

Headers

Path Parameters

Body

Response