## Join a dialog

`POST /v1/openlines/sessions/join`

Adds the current operator to the dialog as one more participant without removing the previous one. Works on any Bitrix24 account and does not wait for the `imopenlines 26.700.0` update.

**Important:** the call changes a live dialog with the client — after it, the operator becomes a participant in the conversation. Permissions are checked by Bitrix24, and a Bitrix24 account administrator passes this check for any dialog in the account.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `chatId` | number \| string | yes | Open Channel chat identifier: a number (`4531`) or a string of the form `chat4531`. `CHAT_ID` is accepted instead of `chatId`, but `dialogId` is not. Sources: [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats) by CRM card, the `sessions[].chatId` field in the [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) response |

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/openlines/sessions/join \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 4531 }'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/openlines/sessions/join \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 4531 }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/join', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 4531 }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
console.log('Joined:', data.joined)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/join', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 4531 }),
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on a successful join |
| `data.chatId` | number | Chat identifier from the request. The `chat4531` form is returned as a number |
| `data.joined` | boolean | Always `true` |

## Response example

```json
{
  "success": true,
  "data": {
    "chatId": 4531,
    "joined": true
  }
}
```

## Error response example

400 — `chatId` was not passed:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "A chat id is required — pass one of: chatId, CHAT_ID. Take it from `data.chat.id` of the bot event (its `data.dialogId` twin is the same id prefixed with `chat`), or from `sessions[].chatId` of POST /v1/openlines/sessions/search."
  }
}
```

## Errors

| HTTP | Code | Description |
|:----:|-----|---------|
| 400 | `MISSING_PARAMS` | `chatId` was not passed |
| 400 | `INVALID_PARAMS` | `chatId` does not parse into a chat identifier: a positive integer and the `chat<N>` form are accepted. The same code when the request body is not a JSON object |
| 400 | `INVALID_JSON_BODY` | The request body does not parse as JSON |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | The key was not recognized |
| 401 | `TOKEN_MISSING` | The personal key has no access to the Bitrix24 account, or the application key was sent without a session token in `Authorization` |
| 403 | `SCOPE_DENIED` | The key has no `imopenlines` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only, while `sessions/join` changes the dialog |
| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no access to the dialog |
| 422 | `BITRIX_ERROR` | Bitrix24 refused, and its code comes in `error.b24Code`: `CHAT_ID` — a chat with this identifier does not exist, `CHAT_TYPE` — the chat is not an Open Channel. The `error.message` text comes from Bitrix24 verbatim, in the Bitrix24 account language |
| 429 | `RATE_LIMITED` | Two sources return this code. The first is the platform's own operation limit: a platform ceiling of 120 requests per minute per Bitrix24 account rather than per key, split across replicas. Take the effective value from the `x-ratelimit-limit` header, the remaining quota and the reset time from `x-ratelimit-remaining` and `x-ratelimit-reset`. These headers come with every response. The second is Bitrix24 rejecting the call under its request rate limit: the response carries a `Retry-After` header |
| 502 | `OPENLINE_SESSION_FAILED` | Bitrix24 responded without confirmation — `result` is not `true`, yet it returned no error |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of an unexpected shape |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the call but did not respond within the allotted time. The call may still have been executed |

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

## Known specifics

- **Dialog completion is not checked.** Joining succeeds even on a dialog whose session closed long ago: the operator is added to the chat participants, and the response is `joined: true`. To work only with open dialogs, take `chatId` from [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats) without `activeOnly=false`.
- **Joining again is not an error.** Calling it for an operator who is already in the dialog returns `joined: true` again.
- **The join is visible in the participant list.** After the call, the operator appears among the Open Channel chat participants — this is how to check that the call took effect.

## See also

- [Intercept a dialog](/docs/openlines/sessions/intercept)
- [Chats by CRM card](/docs/openlines/crm-chats)
- [Session search](/docs/openlines/sessions/search)
- [Session history](/docs/openlines/history)
- [Open Channel sessions](/docs/openlines/sessions)