## Пригласить гостей по почте

`POST /v1/chats/:dialogId/guest-invites/email`

Отправляет людям вне портала приглашения в чат на почту: на каждый адрес создаётся персональная гостевая ссылка, и Битрикс24 присылает её письмом. За один вызов — до 10 приглашений.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `dialogId` (path) | string | да | ID диалога: `chatXXX` для группового чата, числовой ID пользователя для личного, `me` — ваш личный диалог. Список — [`GET /v1/chats/recent`](/docs/chats/discovery/recent) |

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `invitations` | array | да | Приглашения, от 1 до 10 элементов |
| `invitations[].email` | string | да | Адрес гостя, до 254 символов |
| `invitations[].name` | string \| null | нет | Имя гостя для текста приглашения, до 255 символов |

Другие поля тела и элементов, а также параметры запроса отклоняются с `400 INVALID_PARAMS`.

## Примеры

### curl — личный ключ

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/guest-invites/email" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"email": "guest@example.invalid", "name": "Alex"}]}'
```

### curl — OAuth-приложение

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/guest-invites/email" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"email": "guest@example.invalid", "name": "Alex"}]}'
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/guest-invites/email', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ invitations: [{ email: 'guest@example.invalid', name: 'Alex' }] }),
})

const { data } = await res.json()
for (const item of data) {
  console.log(item.email, item.error ? `не отправлено: ${item.error.code}` : 'отправлено')
}
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/guest-invites/email', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ invitations: [{ email: 'guest@example.invalid', name: 'Alex' }] }),
})

const { data } = await res.json()
for (const item of data) {
  console.log(item.email, item.error ? `не отправлено: ${item.error.code}` : 'отправлено')
}
```

## Поля ответа

`data` — массив, по элементу на приглашение в порядке запроса. Элемент — либо отправленное приглашение, либо отказ по нему.

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | `true`, даже если часть приглашений не отправлена — итог каждого смотрите в его элементе |
| `data[].email` | string | Адрес из запроса |
| `data[].sharingLink` | object | Только у отправленного. Персональная гостевая ссылка: `entityType` — `guest_chat`, `type` — `custom`, `name` — адрес, `url` — адрес ссылки для гостя, `dateExpire` — через сутки после создания |
| `data[].error.code` | string | Только у отказа. Код отказа — см. «Отказы по элементу» ниже |
| `data[].error.message` | string | Только у отказа. Текст отказа |

### Отказы по элементу

| Код | Когда |
|-----|-------|
| `GUEST_INVITE_INVALID_EMAIL` | Адрес некорректный |
| `GUEST_INVITE_COOLDOWN` | На этот адрес в этот чат уже приглашали за последние 5 минут |
| `GUEST_INVITE_AUTHOR_RATE_LIMIT` | Вы создали 10 гостевых ссылок за последний час — во всех чатах, включая приглашения и отозванные ссылки |
| `GUEST_INVITE_EMAIL_SEND_FAILED` | Письмо не отправилось, ссылка удалена |

## Пример ответа

Первое приглашение отправлено, второе отклонено:

```json
{
  "success": true,
  "data": [
    {
      "sharingLink": {
        "id": 1016,
        "entityId": "42",
        "entityType": "guest_chat",
        "code": "Wd3nTf8cLq2yHs6J",
        "type": "custom",
        "dateCreate": "2026-09-24T23:07:52+00:00",
        "dateExpire": "2026-09-25T23:07:52+00:00",
        "requireApproval": false,
        "url": "https://b24.to/gi/a1b2c3d4e5-Wd3nTf8cLq2yHs6J?IM_DIALOG=chat42&name=Alex",
        "name": "guest@example.invalid"
      },
      "email": "guest@example.invalid"
    },
    {
      "email": "not-an-address@",
      "error": {
        "code": "GUEST_INVITE_INVALID_EMAIL",
        "message": "GUEST_INVITE_INVALID_EMAIL"
      }
    }
  ]
}
```

## Пример ответа при ошибке

400 — поле элемента не принимается:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`invitations[0].phone` is not accepted. Accepted: email, name."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Тело не объект или несёт поле кроме `invitations`, `invitations` нет или в нём не от 1 до 10 элементов, элемент не объект или несёт поле кроме `email` и `name`, `email` пустой или длиннее 254 символов, `name` не строка до 255 символов и не `null`, передан параметр запроса. Сообщение называет номер элемента и поле, значение не повторяет. Проверяется до обращения к Битрикс24 |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку, код портала — в `error.b24Code`. `CHAT_NOT_FOUND` — чата нет на портале |
| 404 | `ENTITY_NOT_FOUND` | Битрикс24 ответил кодом «не найдено» без уточнения, код портала — в `error.b24Code` |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | Не удалось определить пользователя для алиаса `me` |
| 403 | `BITRIX_ACCESS_DENIED` | Нет права приглашать гостей в этот чат — Битрикс24 отказал с кодом `ACCESS_DENIED` |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения — см. [права доступа](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Автовступление в чат.** Вызов может сделать владельца ключа участником открытого чата, даже если операция со ссылкой затем получит отказ. Ключ только для чтения блокируется до обращения к Битрикс24.

**Повтор после обрыва связи не отправит письмо дважды.** Повторное приглашение того же адреса в тот же чат в течение 5 минут получает `GUEST_INVITE_COOLDOWN` вместо второго письма.

**Адрес увидят все участники чата.** Каждое отправленное приглашение оставляет в чате системное сообщение с адресом гостя. Вайбкод тело приглашения в своих журналах не сохраняет.

**Отозвать приглашение нельзя.** Ни [отзыв гостевой ссылки](/docs/chats/sharing/guest-link-revoke), ни [отзыв по коду](/docs/chats/sharing/link-revoke) персональное приглашение не снимают. Приглашение действует до своего `dateExpire`.

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

- [Пригласить гостей по SMS](/docs/chats/sharing/invite-phone)
- [Получить гостевую ссылку](/docs/chats/sharing/guest-link)
- [Получить ссылку по коду](/docs/chats/sharing/link-get)
- [Ссылки и гости](/docs/chats/sharing)