---
title: "Make a BotInstance post a test message (v2)"
method: POST
path: "/v2/agents/{idOrAddress}/bot-instances/{botInstanceId}/test-message"
tags: ["Agents"]
---

# Make a BotInstance post a test message (v2)

`POST /v2/agents/{idOrAddress}/bot-instances/{botInstanceId}/test-message`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/agents/{idOrAddress}/bot-instances/{botInstanceId}/test-message`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

The bot posts a system message into `roomJid`, or into every room it is
currently in when `roomJid` is omitted. Confirms that the bot is
connected and can deliver messages. The AI service's answer is passed
through, status code included.

Owner only. Supports `User JWT` and `B2B Server JWT`.

## Path parameters

- `idOrAddress` string, required
- `botInstanceId` string, required

## Request body

- object
  - `text` string: Message text. Default is "(test message from <bot name>)".
  - `roomJid` string: Only this room. The bot must already be in it.

## Response `200`

```
{ ok: true, sent: number, total: number, results: [{ room: string, ok: boolean, error?: string }] }
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: ``` { error: 'Forbidden', code: 'FORBIDDEN' } ```
- `404`: `AGENT_NOT_FOUND`, `BOT_INSTANCE_NOT_FOUND`, or `BOT_NOT_SPAWNED` (the AI service has no running bot for it).
- `409`: From the AI service: `BOT_OFFLINE` (XMPP not connected), `BOT_NO_ROOMS`, or `BOT_NOT_IN_ROOM` (with the bot's `rooms`).
- `422`: ``` { error: string, code: 'VALIDATION_ERROR' } ```
- `500`: AI service not configured on this install. ``` { error: 'AI_SERVICE_URL/SECRET not configured', code: 'AI_SERVICE_DOWN' } ```
- `502`: The AI service could not be reached. ``` { error: string, code: 'AI_SERVICE_DOWN' } ```

---

[API](https://skmtc.dev/ethora/apis/platform-api.md) · [All operations](https://skmtc.dev/ethora/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ethora/apis/platform-api/revisions/01b6e64378ee?raw)