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
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog 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
Fieldinvitations Typearray Requiredyes DescriptionInvitations, from 1 to 10 items
Fieldinvitations[].phone Typestring Requiredyes DescriptionThe guest's phone number in international format, up to 32 characters
Fieldinvitations[].name Typestring | null Requiredno DescriptionThe 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
Fieldsuccess Typeboolean Descriptiontrue even if some invitations were not sent — check each invitation's outcome in its item
Fielddata[].phone Typestring DescriptionFor a sent invitation — the number in the international E.164 format; for a refusal — the number from the request
Fielddata[].sharingLink Typeobject DescriptionSent 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, name — the guest's number in E.164 format
Fielddata[].error.code Typestring DescriptionRefusals only. The refusal code — see "Per-item refusals" below
Fielddata[].error.message Typestring DescriptionRefusals only. The refusal text

Per-item refusals

Code When
CodeGUEST_INVITE_INVALID_PHONE WhenThe number cannot be parsed as a phone number
CodeGUEST_INVITE_COOLDOWN WhenThis number was already invited to this chat within the last 5 minutes
CodeGUEST_INVITE_AUTHOR_RATE_LIMIT WhenYou have created 10 guest links within the last hour — across all chats, including invitations and revoked links
CodeGUEST_INVITE_SMS_NOT_CONNECTED WhenNo SMS provider is connected on the portal
CodeGUEST_INVITE_SMS_SEND_FAILED WhenThe SMS was not sent, and the link was deleted

Response example

The invitation was sent:

JSON 
{
  "success": true,
  "data": [
    {
      "sharingLink": {
        "id": 5,
        "entityId": "42",
        "entityType": "guest_chat",
        "code": "Kp7rVx2mNq9sTb4H",
        "type": "custom",
        "dateCreate": "2026-10-15T14:28:07+00:00",
        "dateExpire": "2026-10-16T14:28:07+00:00",
        "requireApproval": false,
        "url": "https://b24.to/gi/a1b2c3d4e5-Kp7rVx2mNq9sTb4H?IM_DIALOG=chat42&name=Alex",
        "name": "+12025550123"
      },
      "phone": "+12025550123"
    }
  ]
}

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
HTTP400 CodeINVALID_PARAMS DescriptionThe 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
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the portal code is in error.b24Code. CHAT_NOT_FOUND — the chat does not exist on the portal
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 answered with an unspecified "not found" code; the portal code is in error.b24Code
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionFailed to resolve the user for the me alias
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo right to invite guests to this chat, or a chat of this type does not accept guests — for example, a collab. Bitrix24 refused with the ACCESS_DENIED code
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP401 CodeTOKEN_MISSING DescriptionThe 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