---
title: "Add an AI Agent to a chat (v2)"
method: POST
path: "/v2/agents/{idOrAddress}/invite-to-chat"
tags: ["Agents"]
---

# Add an AI Agent to a chat (v2)

`POST /v2/agents/{idOrAddress}/invite-to-chat`

## Request

- Base URL: `https://api.chat.ethora.com`
- URL: `https://api.chat.ethora.com/v2/agents/{idOrAddress}/invite-to-chat`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Adds the agent to a room. The first invite into an App creates the
agent's BotInstance there (bot user, XMPP account, a running bot);
later invites into that App reuse it. The bot is made a room member,
listed among the room's members, and told to join.

The agent must be the caller's own, or `unlisted` / `public`. The
room must belong to the target App (else 422 `CHAT_APP_MISMATCH`), and
the caller must manage that App (its creator, an admin with
`appSettings.update`, a B2B Server JWT for it, `isSuperAdmin.write`)
or be a member of the room (else 403). Supports `User JWT` and
`B2B Server JWT`.

The target App is `appId` from the body, else the caller's App. Name
the room with `chatJid` (full room JID) or `chatId` (the chat's id).

## Path parameters

- `idOrAddress` string, required

## Request body

- object: One of `chatJid` or `chatId` is required.
  - `appId` string: App the room belongs to. Default is the caller's App.
  - `chatJid` string: Full room JID, `<appId>_<chatId>@conference.<xmpp host>`.
  - `chatId` string: The chat's id; used when `chatJid` is not given.

## Response `200`

```
{
  ok: true,
  created: boolean,           // a new BotInstance was created for this App
  agent: Agent,
  botInstance: {
    id: string, agentId: string, appId: string, userId: string,
    xmppUsername: string, status: 'on'|'off', joinedRooms: string[]
  },
  chatJid: string
}
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: ``` { error: 'Agent is private', code: 'AGENT_PRIVATE' } ```
- `404`: `AGENT_NOT_FOUND`, `APP_NOT_FOUND`, or `CHAT_NOT_FOUND` (no chat with that `chatId`).
- `422`: Neither `chatJid` nor `chatId`, or no App to invite into. ``` { error: string, code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error
- `502`: ``` { error: 'XMPP affiliate/invite failed', code: 'XMPP_UNAVAILABLE', details: { reason: string } } ```

---

[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)