## Get a bot

`GET /v1/bots/:botId`

Retrieves the current bot data from Bitrix24 (a live request, not from cache).

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `botId` | number | yes | Bot ID (path parameter) |

## Examples

### curl — personal key

```bash
curl https://vibecode.bitrix24.com/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl https://vibecode.bitrix24.com/v1/bots/42 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Bot:', data)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Response fields

The response contains two objects: `data.bot` — the bot's parameters, `data.users` — an array of Bitrix24 users representing the bot. The array holds one element — the bot's user account.

| Field | Type | Description |
|------|-----|---------|
| `data.bot.id` | number | Bot ID in the Bitrix24 account |
| `data.bot.code` | string | Unique bot code |
| `data.bot.type` | string | Bot type: `bot`, `personal`, `supervisor`, `openline` |
| `data.bot.isHidden` | boolean | Hidden from the contact list |
| `data.bot.isSupportOpenline` | boolean | Open Channels support |
| `data.bot.isReactionsEnabled` | boolean | Reactions to messages are allowed |
| `data.bot.backgroundId` | string | Chat background. Arrives as `null` when not set |
| `data.bot.language` | string | Bot language, e.g. `ru` |
| `data.bot.moduleId` | string | The module that registered the bot, e.g. `rest` |
| `data.bot.eventMode` | string | Event mode: `fetch` or `webhook` |
| `data.bot.countMessage` | number | Message counter |
| `data.bot.countCommand` | number | Command counter |
| `data.bot.countChat` | number | Chat counter |
| `data.bot.countUser` | number | User counter |
| `data.users[].id` | number | Bot user ID. Matches `data.bot.id` |
| `data.users[].name` | string | Full name |
| `data.users[].firstName` | string | First name |
| `data.users[].lastName` | string | Last name. Empty string when not set |
| `data.users[].workPosition` | string | Job title |
| `data.users[].color` | string | Avatar color in HEX format, e.g. `#29619b` |
| `data.users[].avatar` | string | Avatar URL. Empty string when not set |
| `data.users[].gender` | string | Gender: `M` or `F` |
| `data.users[].active` | boolean | Whether the user is active |
| `data.users[].bot` | boolean | Bot flag |
| `data.users[].departments` | array | Departments. Empty array when there are none |
| `data.users[].lastActivityDate` | string or false | Time of last activity. Arrives as `false` when there was no activity |

The `data.users` array also carries other standard Bitrix24 user fields — `birthday`, `phones`, `website`, `email`, `status`, `mobileLastDate`, `desktopLastDate`. How empty values are encoded is covered in "Known specifics".

## Response example

```json
{
  "success": true,
  "data": {
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "isHidden": false,
      "isSupportOpenline": false,
      "isReactionsEnabled": true,
      "backgroundId": null,
      "language": "ru",
      "moduleId": "rest",
      "eventMode": "fetch",
      "countMessage": 0,
      "countCommand": 0,
      "countChat": 0,
      "countUser": 0
    },
    "users": [
      {
        "id": 42,
        "active": true,
        "name": "Support",
        "firstName": "Support",
        "lastName": "",
        "workPosition": "Technical support assistant",
        "color": "#29619b",
        "avatar": "",
        "gender": "M",
        "bot": true,
        "departments": [],
        "lastActivityDate": false,
        "phones": false
      }
    ]
  }
}
```

## Error response example

404 — bot not found:

```json
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` is not a number |
| 404 | `BOT_NOT_FOUND` | Bot not found — register it via `POST /v1/bots` |
| 403 | `BOT_ACCESS_DENIED` | The bot belongs to a different API key |
| 403 | `SCOPE_DENIED` | The API key does not have the `imbot` scope |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Empty values are encoded differently.** In `data.users[]` an empty field arrives in one of several forms depending on its type: an empty string `""` (`lastName`, `avatar`, `birthday`, `website`, `email`), `false` (the dates `lastActivityDate`, `mobileLastDate`, `desktopLastDate` and the `phones` list), an empty array `[]` (`departments`). In `data.bot` an unset `backgroundId` arrives as `null`. Check a field's form before using it: `new Date(false)` and `phones.map(...)` on a `false` value produce incorrect results.

**Avatar color is returned in HEX.** On write, `color` accepts a palette name (`AZURE`, `MINT`, …), but in the response `data.users[].color` arrives as a HEX string, e.g. `#29619b`. The written palette name cannot be read back.

## See also

- [List bots](/docs/bots/management)
- [Update a bot](/docs/bots/management)
- [Events](/docs/bots/events)
- [Limits and optimization](/docs/optimization)