## Get an individual chat link

`POST /v1/chats/:dialogId/sharing-links/individual`

Returns your individual chat link and creates it if the link does not exist yet. An employee of the Bitrix24 account joins the chat with the link code, and each member has their own link.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `dialogId` (path) | string | yes | Dialog ID: `chatXXX` for a group chat, a numeric user ID for a private chat, `me` — your personal dialog. List — [`GET /v1/chats/recent`](/docs/chats/discovery/recent) |

## Request fields (body)

The body is optional.

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `generateIfNotExists` | boolean | no | `false` — only return the existing link without creating a new one. Defaults to `true` |

Other body fields and query parameters are rejected with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/individual" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/individual" \
  -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/chats/chat42/sharing-links/individual', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Link code:', data.sharingLink.code)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/individual', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Link code:', data.sharingLink.code)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.sharingLink.id` | number | Link ID |
| `data.sharingLink.entityType` | string | `chat` — a chat link |
| `data.sharingLink.entityId` | string | Chat ID without the `chat` prefix |
| `data.sharingLink.code` | string | The link code — for [joining by code](/docs/chats/sharing/join), reading and revoking |
| `data.sharingLink.type` | string | `individual` — an individual link |
| `data.sharingLink.dateCreate` | string | Creation date, ISO 8601 |
| `data.sharingLink.dateExpire` | string \| null | Expiration date. `null` — no expiration |
| `data.sharingLink.requireApproval` | boolean | Whether joining requires approval |
| `data.sharingLink.url` | string | The link URL on the Bitrix24 account; the code is the value of its `IM_CODE` parameter |

## Response example

```json
{
  "success": true,
  "data": {
    "sharingLink": {
      "id": 1012,
      "entityId": "42",
      "entityType": "chat",
      "code": "Xk9pQ2mZ7rT4vB1c",
      "type": "individual",
      "dateCreate": "2026-09-24T23:02:28+00:00",
      "dateExpire": null,
      "requireApproval": false,
      "url": "https://portal.bitrix24.com/online/?IM_CODE=Xk9pQ2mZ7rT4vB1c"
    }
  }
}
```

## Error response example

422 — there is no link, and `generateIfNotExists` is `false`:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "SHARING_LINK_NOT_FOUND",
    "b24Code": "SHARING_LINK_NOT_FOUND"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | A body field other than `generateIfNotExists`, a body that is not an object, a `generateIfNotExists` that is neither `true` nor `false`, or a query parameter. Checked before any call to Bitrix24 |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error; the portal code is in `error.b24Code`. `SHARING_LINK_NOT_FOUND` — no link exists with `generateIfNotExists: false`. `CHAT_NOT_FOUND` — the chat does not exist on the portal |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 answered with an unspecified "not found" code; the portal code is in `error.b24Code` |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | Failed to resolve the user for the `me` alias |
| 403 | `BITRIX_ACCESS_DENIED` | No right to invite to this chat — Bitrix24 refused with the `ACCESS_DENIED` code |
| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only and the call is a write — see [access rights](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |

The full list of general API errors — [Errors](/docs/errors).

## Known specifics

**A repeated call returns the same link.** While the link is valid, every call returns it with the same `code`. A new code comes from [regeneration](/docs/chats/sharing/individual-link-regenerate).

**The call is a write even without creating a link.** With `generateIfNotExists: false`, no link is created, but a read-only key still gets `403 WRITE_BLOCKED_READONLY_KEY`: the call may make the key owner a chat member if the chat allows auto-join.

## See also

- [Regenerate an individual link](/docs/chats/sharing/individual-link-regenerate)
- [Revoke a link by code](/docs/chats/sharing/link-revoke)
- [Join a chat by code](/docs/chats/sharing/join)
- [Links and guests](/docs/chats/sharing)