Dành cho AI agent: markdown của trang này — /docs-content-en/chats/sharing.md chỉ mục tài liệu — /llms.txt

Hiện tại, các bài viết trong tài liệu chỉ có bằng tiếng Anh.

Links and guests

Invite employees of the Bitrix24 account to a chat by link, and people outside the Bitrix24 account — guests — by guest link, email or SMS. Revocation depends on the link type: personal email and SMS invitations cannot be revoked.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Bitrix24 API: im.v2.Chat.SharingLink.*, im.v2.SharingLink.get, im.v2.Chat.joinByCode, im.v2.Guest.Link.*

POST /v1/chats/:dialogId/sharing-links/primary

Returns the primary chat link and creates it if the link does not exist yet. A chat has one primary link, which cannot be revoked, and only a member with the right to manage the chat's links can obtain it.

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

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

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/primary" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"generateIfNotExists": false}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/primary" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"generateIfNotExists": false}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/primary', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ generateIfNotExists: false }),
})

const { success, data, error } = await res.json()
console.log(success ? data.sharingLink.code : error.code)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/sharing-links/primary', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ generateIfNotExists: false }),
})

const { success, data, error } = await res.json()
console.log(success ? data.sharingLink.code : error.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 and for reading the link
data.sharingLink.type string primary — the primary 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

A link object of the same shape as for an individual link, with type equal to primary:

JSON 
{
  "success": true,
  "data": {
    "sharingLink": {
      "id": 1011,
      "entityId": "42",
      "entityType": "chat",
      "code": "Rt5wYn8KqL2vPz3M",
      "type": "primary",
      "dateCreate": "2026-09-24T23:01:10+00:00",
      "dateExpire": null,
      "requireApproval": false,
      "url": "https://portal.bitrix24.com/online/?IM_CODE=Rt5wYn8KqL2vPz3M"
    }
  }
}

Error response example

403 — a group chat, where the primary link is not issued to any member:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "ACCESS_DENIED"
  }
}

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
403 BITRIX_ACCESS_DENIED No right to manage the chat's links — Bitrix24 refused with the ACCESS_DENIED code
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. SHARING_LINK_NOT_FOUND — no link exists and generateIfNotExists: false was passed. 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 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
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of general API errors — Errors.

Known specifics

A group chat does not issue a primary link. Bitrix24 grants no member, not even the owner, the right to manage a group chat's links, so the call returns 403 BITRIX_ACCESS_DENIED. To invite an employee to such a chat by link, give them your individual link.

The primary link cannot be revoked. Revoking by code removes only individual links.

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