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

Invite guests by email

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

Sends chat invitations by email to people outside the Bitrix24 account: a personal guest link is created for each address, and Bitrix24 sends it in an email. 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[].email string yes The guest's email address, up to 254 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/email" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invitations": [{"email": "guest@example.invalid", "name": "Alex"}]}'

curl — OAuth application

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

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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 ? `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[].email string The address from the request
data[].sharingLink object Sent invitations only. The personal guest link: entityType — guest_chat, type — custom, name — the email address, url — the link URL for the guest, dateExpire — one day after creation
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_EMAIL The address is invalid
GUEST_INVITE_COOLDOWN This address 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_EMAIL_SEND_FAILED The email was not sent, and the link was deleted

Response example

The first invitation is sent, the second is refused:

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"
      }
    }
  ]
}

Error response example

400 — an item field is not accepted:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`invitations[0].phone` is not accepted. Accepted: email, 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 email and name; email is empty or longer than 254 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 email twice. Re-inviting the same address to the same chat within 5 minutes is refused with GUEST_INVITE_COOLDOWN instead of sending a second email.

All chat members will see the address. Every invitation sent leaves a system message with the guest's address 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