Для AI-агентов: markdown этой страницы — /docs-content/chats/sharing/invite-email.md индекс документации — /llms.txt

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

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

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

Параметры

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

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

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

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

Примеры

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

Terminal 
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-приложение

Terminal 
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 Ключ только для чтения — см. права доступа
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24

Полный список общих ошибок API — Ошибки.

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

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

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

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

Отозвать приглашение нельзя. Ни отзыв гостевой ссылки, ни отзыв по коду персональное приглашение не снимают. Приглашение действует до своего dateExpire.

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