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

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

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

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

Параметры

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

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

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

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

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/guest-invites/phone" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"phone": "+12025550123", "name": "Alex"}]}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/chats/chat42/guest-invites/phone" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"phone": "+12025550123", "name": "Alex"}]}'

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

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

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

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

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

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

Поля ответа

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

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

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

Код Когда
GUEST_INVITE_INVALID_PHONE Номер не читается как телефонный
GUEST_INVITE_COOLDOWN На этот номер в этот чат уже приглашали за последние 5 минут
GUEST_INVITE_AUTHOR_RATE_LIMIT Вы создали 10 гостевых ссылок за последний час — во всех чатах, включая приглашения и отозванные ссылки
GUEST_INVITE_SMS_NOT_CONNECTED На портале не подключён провайдер SMS
GUEST_INVITE_SMS_SEND_FAILED SMS не отправилось, ссылка удалена

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

Номер не читается как телефонный:

JSON 
{
  "success": true,
  "data": [
    {
      "phone": "not-a-phone",
      "error": {
        "code": "GUEST_INVITE_INVALID_PHONE",
        "message": "GUEST_INVITE_INVALID_PHONE"
      }
    }
  ]
}

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

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

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

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Тело не объект или несёт поле кроме invitations, invitations нет или в нём не от 1 до 10 элементов, элемент не объект или несёт поле кроме phone и name, phone пустой или длиннее 32 символов, 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.

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

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

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

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