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

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

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

## Параметры

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

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

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

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

## Примеры

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

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

```bash
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 | Только у отправленного. Персональная гостевая ссылка того же вида, что у [приглашения по почте](/docs/chats/sharing/invite-email): `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` | Ключ только для чтения — см. [права доступа](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |

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

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

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

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

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

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

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

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