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
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[].email Typestring Requiredyes DescriptionThe guest's email address, up to 254 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/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
Fieldsuccess Typeboolean Descriptiontrue even if some invitations were not sent — check each invitation's outcome in its item
Fielddata[].email Typestring DescriptionThe address from the request
Fielddata[].sharingLink Typeobject DescriptionSent 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
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_EMAIL WhenThe address is invalid
CodeGUEST_INVITE_COOLDOWN WhenThis address 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_EMAIL_SEND_FAILED WhenThe 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
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 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
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 — 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 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