# Ссылки и гости

Приглашайте в чат сотрудников портала по ссылке, а людей вне портала — гостей — по гостевой ссылке, почте или SMS. Возможность отзыва зависит от вида ссылки: персональные приглашения по почте и SMS отозвать нельзя.

**Скоуп:** `im` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

Битрикс24 API: `im.v2.Chat.SharingLink.*`, `im.v2.SharingLink.get`, `im.v2.Chat.joinByCode`, `im.v2.Guest.Link.*`

## Операции

- [Получить основную ссылку чата](./sharing/primary-link.md) — `POST /v1/chats/:dialogId/sharing-links/primary`
- [Получить личную ссылку на чат](./sharing/individual-link.md) — `POST /v1/chats/:dialogId/sharing-links/individual`
- [Перевыпустить личную ссылку](./sharing/individual-link-regenerate.md) — `POST /v1/chats/:dialogId/sharing-links/individual/regenerate`
- [Получить ссылку по коду](./sharing/link-get.md) — `GET /v1/chats/sharing-links/:code`
- [Отозвать ссылку по коду](./sharing/link-revoke.md) — `DELETE /v1/chats/sharing-links/:code`
- [Вступить в чат по коду](./sharing/join.md) — `POST /v1/chats/join-by-code`
- [Получить гостевую ссылку](./sharing/guest-link.md) — `POST /v1/chats/:dialogId/guest-links`
- [Перевыпустить гостевую ссылку](./sharing/guest-link-regenerate.md) — `POST /v1/chats/:dialogId/guest-links/regenerate`
- [Отозвать гостевую ссылку](./sharing/guest-link-revoke.md) — `DELETE /v1/chats/:dialogId/guest-links`
- [Пригласить гостей по почте](./sharing/invite-email.md) — `POST /v1/chats/:dialogId/guest-invites/email`
- [Пригласить гостей по SMS](./sharing/invite-phone.md) — `POST /v1/chats/:dialogId/guest-invites/phone`

## Два вида ссылок

Эндпоинты, которые выдают или читают ссылку, возвращают её объектом `sharingLink`, у приглашений он лежит в элементе ответа. Вид ссылки определяют поля `entityType` и `type`.

| | Ссылка на чат | Гостевая ссылка |
|---|---|---|
| Кто входит | Сотрудник портала — [вступлением по коду](/docs/chats/sharing/join) | Человек вне портала — по адресу из поля `url` в браузере |
| `entityType` | `chat` | `guest_chat` |
| `type` | `primary` — основная ссылка, одна на чат. `individual` — личная ссылка, у каждого участника своя | `individual` — личная гостевая ссылка участника. `custom` — персональное приглашение по почте или SMS |
| `dateExpire` | `null` — без срока | Через сутки после создания |

`code` — код ссылки. Ссылка на чат содержит его в параметре `IM_CODE`: по коду её читают и вступают в чат. По коду отзываются только личные ссылки; основная ссылка чата не отзывается, персональные приглашения по почте и SMS действуют до `dateExpire`. Свою гостевую ссылку можно отозвать, но гостю для входа нужен её `url`, а не `join-by-code`.

## Типовой сценарий

1. Получите свою личную ссылку на чат — `POST /v1/chats/:dialogId/sharing-links/individual` — и передайте её `code` коллеге.
2. Коллега вступает в чат — `POST /v1/chats/join-by-code` с этим кодом.
3. Когда ссылка больше не нужна, отзовите её — `DELETE /v1/chats/sharing-links/:code`.

## Что нужно знать

**Код ссылки — это доступ к чату.** Кто знает код, тот вступает в чат. Передавайте код и адрес ссылки только по защищённому каналу. Код стоит в пути запросов `GET` и `DELETE /v1/chats/sharing-links/:code`, а путь запроса записывают журналы прокси-серверов по дороге к API.

**Все вызовы, кроме чтения по коду, изменяющие.** Эндпоинты с `dialogId` в пути создают, перевыпускают или отзывают ссылки и могут сделать вас участником чата, если чат разрешает автовступление. Ключ только для чтения получает на них `403 WRITE_BLOCKED_READONLY_KEY` до обращения к Битрикс24 — даже при `generateIfNotExists: false`. Чтение [ссылки по коду](/docs/chats/sharing/link-get) ключу только для чтения доступно. Подробнее — [права доступа](/docs/access-rights).

**Приглашения содержат данные людей вне портала.** Адреса и телефоны из тела приглашения Вайбкод в своих журналах не сохраняет. При этом каждое отправленное приглашение оставляет в чате системное сообщение с адресом или номером, и его видят все участники.

## Смотрите также

- [Чаты и сообщения](/docs/chats)
- [Участники](/docs/chats/members)
- [Права доступа](/docs/access-rights)