[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-chats\u002Fsharing\u002Finvite-email":3,"docs-tabs-chats\u002Fsharing\u002Finvite-email":6},{"content":4,"lastmod":5},"## Invite guests by email\n\n`POST \u002Fv1\u002Fchats\u002F:dialogId\u002Fguest-invites\u002Femail`\n\nSends 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.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `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 \u002Fv1\u002Fchats\u002Frecent`](\u002Fdocs\u002Fchats\u002Fdiscovery\u002Frecent) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `invitations` | array | yes | Invitations, from 1 to 10 items |\n| `invitations[].email` | string | yes | The guest's email address, up to 254 characters |\n| `invitations[].name` | string \\| null | no | The guest's name for the invitation text, up to 255 characters |\n\nOther body and item fields, as well as query parameters, are rejected with `400 INVALID_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fguest-invites\u002Femail\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"invitations\": [{\"email\": \"guest@example.invalid\", \"name\": \"Alex\"}]}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fguest-invites\u002Femail\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"invitations\": [{\"email\": \"guest@example.invalid\", \"name\": \"Alex\"}]}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fguest-invites\u002Femail', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ invitations: [{ email: 'guest@example.invalid', name: 'Alex' }] }),\n})\n\nconst { data } = await res.json()\nfor (const item of data) {\n  console.log(item.email, item.error ? `not sent: ${item.error.code}` : 'sent')\n}\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fguest-invites\u002Femail', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ invitations: [{ email: 'guest@example.invalid', name: 'Alex' }] }),\n})\n\nconst { data } = await res.json()\nfor (const item of data) {\n  console.log(item.email, item.error ? `not sent: ${item.error.code}` : 'sent')\n}\n```\n\n## Response fields\n\n`data` is an array with one item per invitation, in request order. An item is either a sent invitation or a refusal for it.\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` even if some invitations were not sent — check each invitation's outcome in its item |\n| `data[].email` | string | The address from the request |\n| `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 |\n| `data[].error.code` | string | Refusals only. The refusal code — see \"Per-item refusals\" below |\n| `data[].error.message` | string | Refusals only. The refusal text |\n\n### Per-item refusals\n\n| Code | When |\n|-----|-------|\n| `GUEST_INVITE_INVALID_EMAIL` | The address is invalid |\n| `GUEST_INVITE_COOLDOWN` | This address was already invited to this chat within the last 5 minutes |\n| `GUEST_INVITE_AUTHOR_RATE_LIMIT` | You have created 10 guest links within the last hour — across all chats, including invitations and revoked links |\n| `GUEST_INVITE_EMAIL_SEND_FAILED` | The email was not sent, and the link was deleted |\n\n## Response example\n\nThe first invitation is sent, the second is refused:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"sharingLink\": {\n        \"id\": 1016,\n        \"entityId\": \"42\",\n        \"entityType\": \"guest_chat\",\n        \"code\": \"Wd3nTf8cLq2yHs6J\",\n        \"type\": \"custom\",\n        \"dateCreate\": \"2026-09-24T23:07:52+00:00\",\n        \"dateExpire\": \"2026-09-25T23:07:52+00:00\",\n        \"requireApproval\": false,\n        \"url\": \"https:\u002F\u002Fb24.to\u002Fgi\u002Fa1b2c3d4e5-Wd3nTf8cLq2yHs6J?IM_DIALOG=chat42&name=Alex\",\n        \"name\": \"guest@example.invalid\"\n      },\n      \"email\": \"guest@example.invalid\"\n    },\n    {\n      \"email\": \"not-an-address@\",\n      \"error\": {\n        \"code\": \"GUEST_INVITE_INVALID_EMAIL\",\n        \"message\": \"GUEST_INVITE_INVALID_EMAIL\"\n      }\n    }\n  ]\n}\n```\n\n## Error response example\n\n400 — an item field is not accepted:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"`invitations[0].phone` is not accepted. Accepted: email, name.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 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 |\n| 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 |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 answered with an unspecified \"not found\" code; the portal code is in `error.b24Code` |\n| 502 | `ME_ALIAS_RESOLUTION_FAILED` | Failed to resolve the user for the `me` alias |\n| 403 | `BITRIX_ACCESS_DENIED` | No right to invite guests to this chat — Bitrix24 refused with the `ACCESS_DENIED` code |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — see [access rights](\u002Fdocs\u002Faccess-rights) |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n\nThe full list of general API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**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.\n\n**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.\n\n**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.\n\n**An invitation cannot be revoked.** Neither [guest link revocation](\u002Fdocs\u002Fchats\u002Fsharing\u002Fguest-link-revoke) nor [revoking by code](\u002Fdocs\u002Fchats\u002Fsharing\u002Flink-revoke) removes a personal invitation. The invitation remains valid until its `dateExpire`.\n\n## See also\n\n- [Invite guests by SMS](\u002Fdocs\u002Fchats\u002Fsharing\u002Finvite-phone)\n- [Get a guest link](\u002Fdocs\u002Fchats\u002Fsharing\u002Fguest-link)\n- [Get a link by code](\u002Fdocs\u002Fchats\u002Fsharing\u002Flink-get)\n- [Links and guests](\u002Fdocs\u002Fchats\u002Fsharing)\n","2026-10-01",{},1794739554076]