---
title: "Make an AI Agent the App's website widget responder (v2, app-token)"
method: POST
path: "/v2/agents/{idOrAddress}/activate"
tags: ["Agents"]
---

# Make an AI Agent the App's website widget responder (v2, app-token)

`POST /v2/agents/{idOrAddress}/activate`

## Request

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

Invites the agent into the App's AI Widget chat (as
`POST /v2/agents/{idOrAddress}/invite-to-chat` does) and sets the
resulting BotInstance as the App's `defaultBotInstanceId`, the bot that
answers website widget visitors. AppId is inferred from the app-token
(authMw('app')).

The room is `chatJid` from the body, else the App's bound AI Widget
chat; it must be one of this App's rooms (else 422
`CHAT_APP_MISMATCH`). The agent must be owned by the App or be
`unlisted` / `public`.

## Path parameters

- `idOrAddress` string, required

## Request body

- object
  - `chatJid` string: Room to use instead of the App's AI Widget chat.

## Response `200`

```
{ ok: true, agent: Agent, botInstance: { id, agentId, appId, userId, xmppUsername, status, joinedRooms }, defaultBotInstanceId: string|null }
```

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: ``` { error: 'Agent is private', code: 'AGENT_PRIVATE' } ```
- `404`: `APP_NOT_FOUND` or `AGENT_NOT_FOUND`.
- `422`: The App has no AI Widget chat bound and no `chatJid` was given. ``` { error: 'AI Widget chat not bound; bind one first or pass chatJid', code: 'VALIDATION_ERROR' } ```
- `500`: Internal Server Error
- `502`: ``` { error: 'XMPP affiliate/invite failed', code: 'XMPP_UNAVAILABLE' } ```

---

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