# 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.*`

## Operations

- [Get the primary chat link](./sharing/primary-link.md) — `POST /v1/chats/:dialogId/sharing-links/primary`
- [Get an individual chat link](./sharing/individual-link.md) — `POST /v1/chats/:dialogId/sharing-links/individual`
- [Regenerate an individual link](./sharing/individual-link-regenerate.md) — `POST /v1/chats/:dialogId/sharing-links/individual/regenerate`
- [Get a link by code](./sharing/link-get.md) — `GET /v1/chats/sharing-links/:code`
- [Revoke a link by code](./sharing/link-revoke.md) — `DELETE /v1/chats/sharing-links/:code`
- [Join a chat by code](./sharing/join.md) — `POST /v1/chats/join-by-code`
- [Get a guest link](./sharing/guest-link.md) — `POST /v1/chats/:dialogId/guest-links`
- [Regenerate a guest link](./sharing/guest-link-regenerate.md) — `POST /v1/chats/:dialogId/guest-links/regenerate`
- [Revoke a guest link](./sharing/guest-link-revoke.md) — `DELETE /v1/chats/:dialogId/guest-links`
- [Invite guests by email](./sharing/invite-email.md) — `POST /v1/chats/:dialogId/guest-invites/email`
- [Invite guests by SMS](./sharing/invite-phone.md) — `POST /v1/chats/:dialogId/guest-invites/phone`

## Two kinds of links

Endpoints that issue or read a link return it as a `sharingLink` object; for invitations, the object is nested in the invitation's response item. The kind of link is defined by the `entityType` and `type` fields.

| | Chat link | Guest link |
|---|---|---|
| Who joins | An employee of the Bitrix24 account — [by code](/docs/chats/sharing/join) | A person outside the Bitrix24 account — by opening the address from the `url` field in a browser |
| `entityType` | `chat` | `guest_chat` |
| `type` | `primary` — the primary link, one per chat. `individual` — an individual link; each member has their own | `individual` — a member's individual guest link. `custom` — a personal invitation by email or SMS |
| `dateExpire` | `null` — no expiration | One day after creation |

`code` is the link code. A chat link carries it in the `IM_CODE` parameter: it can be read by code and used to join the chat. Only individual links can be revoked by code; a primary chat link cannot be revoked, and personal email and SMS invitations remain valid until `dateExpire`. Your own guest link can be revoked, but a guest joins through its `url`, not `join-by-code`.

## Typical scenario

1. Get your individual chat link — `POST /v1/chats/:dialogId/sharing-links/individual` — and pass its `code` to a colleague.
2. The colleague joins the chat — `POST /v1/chats/join-by-code` with this code.
3. When the link is no longer needed, revoke it — `DELETE /v1/chats/sharing-links/:code`.

## What you need to know

**A link code grants access to the chat.** Anyone who knows the code can join the chat. Share the code and the link address only over a secure channel. The code sits in the path of the `GET` and `DELETE /v1/chats/sharing-links/:code` requests, and the request path is recorded in the logs of proxy servers on the way to the API.

**Every call except reading by code is a write.** Endpoints with `dialogId` in the path create, regenerate or revoke links and may make you a chat member if the chat allows auto-join. A read-only key gets `403 WRITE_BLOCKED_READONLY_KEY` on them before any call to Bitrix24 — even with `generateIfNotExists: false`. A read-only key can read a [link by code](/docs/chats/sharing/link-get). For details, see [access rights](/docs/access-rights).

**Invitations contain data about people outside the Bitrix24 account.** Vibecode does not store the addresses and phone numbers from the invitation body in its logs. However, every invitation sent leaves a system message with the address or number in the chat, and all members see it.

## See also

- [Chats and messages](/docs/chats)
- [Members](/docs/chats/members)
- [Access rights](/docs/access-rights)