For AI agents: markdown of this page — /docs-content-en/chats/sharing/invite-phone.md documentation index — /llms.txt

Invite guests by SMS

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

Sends chat invitations by SMS to people outside the Bitrix24 account: a personal guest link is created for each number, and Bitrix24 sends it in a text message. Up to 10 invitations per call.

Parameters

Parameter Type Required Description
dialogId (path) string yes Dialog ID: chatXXX for a group chat, a numeric user ID for a private chat, me — your personal dialog. List — GET /v1/chats/recent

Request fields (body)

Field Type Required Description
invitations array yes Invitations, from 1 to 10 items
invitations[].phone string yes The guest's phone number in international format, up to 32 characters
invitations[].name string | null no The guest's name for the invitation text, up to 255 characters

Other body and item fields, as well as query parameters, are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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 ? `not sent: ${item.error.code}` : 'sent')
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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 ? `not sent: ${item.error.code}` : 'sent')
}

Response fields

data is an array with one item per invitation, in request order. An item is either a sent invitation or a refusal for it.

Field Type Description
success boolean true even if some invitations were not sent — check each invitation's outcome in its item
data[].phone string For a sent invitation — the number in the international E.164 format; for a refusal — the number from the request
data[].sharingLink object Sent invitations only. A personal guest link of the same shape as for an email invitation: entityType — guest_chat, type — custom, url — the link URL for the guest
data[].error.code string Refusals only. The refusal code — see "Per-item refusals" below
data[].error.message string Refusals only. The refusal text

Per-item refusals

Code When
GUEST_INVITE_INVALID_PHONE The number cannot be parsed as a phone number
GUEST_INVITE_COOLDOWN This number was already invited to this chat within the last 5 minutes
GUEST_INVITE_AUTHOR_RATE_LIMIT You have created 10 guest links within the last hour — across all chats, including invitations and revoked links
GUEST_INVITE_SMS_NOT_CONNECTED No SMS provider is connected on the portal
GUEST_INVITE_SMS_SEND_FAILED The SMS was not sent, and the link was deleted

Response example

The number cannot be parsed as a phone number:

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

Error response example

400 — an item field is not accepted:

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

Errors

HTTP Code Description
400 INVALID_PARAMS The body is not an object or carries a field other than invitations; invitations is missing or does not hold from 1 to 10 items; an item is not an object or carries a field other than phone and name; phone is empty or longer than 32 characters; name is neither a string of up to 255 characters nor null; a query parameter was passed. The message names the item index and the field and does not repeat the value. Checked before any call to Bitrix24
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. CHAT_NOT_FOUND — the chat does not exist on the portal
404 ENTITY_NOT_FOUND Bitrix24 answered with an unspecified "not found" code; the portal code is in error.b24Code
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user for the me alias
403 BITRIX_ACCESS_DENIED No right to invite guests to this chat — Bitrix24 refused with the ACCESS_DENIED code
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of general API errors — Errors.

Known specifics

Automatic chat membership. The call can make the key owner a member of a chat that allows auto-join, even if the link operation is subsequently refused. A read-only key is blocked before Bitrix24 is called.

A retry after a dropped connection does not send the SMS twice. Re-inviting the same number to the same chat within 5 minutes is refused with GUEST_INVITE_COOLDOWN instead of sending a second message.

All chat members will see the number. Every invitation sent leaves a system message with the guest's number in the chat. Vibecode does not store the invitation body in its logs.

An invitation cannot be revoked. Neither guest link revocation nor revoking by code removes a personal invitation. The invitation remains valid until its dateExpire.

See also