[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-chats\u002Fsharing\u002Finvite-phone":3,"docs-tabs-chats\u002Fsharing\u002Finvite-phone":6},{"content":4,"lastmod":5},"## Invite guests by SMS\n\n`POST \u002Fv1\u002Fchats\u002F:dialogId\u002Fguest-invites\u002Fphone`\n\nSends 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.\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[].phone` | string | yes | The guest's phone number in international format, up to 32 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\u002Fphone\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"invitations\": [{\"phone\": \"+12025550123\", \"name\": \"Alex\"}]}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fchat42\u002Fguest-invites\u002Fphone\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"invitations\": [{\"phone\": \"+12025550123\", \"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\u002Fphone', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ invitations: [{ phone: '+12025550123', name: 'Alex' }] }),\n})\n\nconst { data } = await res.json()\nfor (const item of data) {\n  console.log(item.phone, 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\u002Fphone', {\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: [{ phone: '+12025550123', name: 'Alex' }] }),\n})\n\nconst { data } = await res.json()\nfor (const item of data) {\n  console.log(item.phone, 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[].phone` | string | For a sent invitation — the number in the international E.164 format; for a refusal — the number from the request |\n| `data[].sharingLink` | object | Sent invitations only. A personal guest link of the same shape as for an [email invitation](\u002Fdocs\u002Fchats\u002Fsharing\u002Finvite-email): `entityType` — `guest_chat`, `type` — `custom`, `url` — the link URL for the guest, `name` — the guest's number in E.164 format |\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_PHONE` | The number cannot be parsed as a phone number |\n| `GUEST_INVITE_COOLDOWN` | This number 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_SMS_NOT_CONNECTED` | No SMS provider is connected on the portal |\n| `GUEST_INVITE_SMS_SEND_FAILED` | The SMS was not sent, and the link was deleted |\n\n## Response example\n\nThe invitation was sent:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"sharingLink\": {\n        \"id\": 5,\n        \"entityId\": \"42\",\n        \"entityType\": \"guest_chat\",\n        \"code\": \"Kp7rVx2mNq9sTb4H\",\n        \"type\": \"custom\",\n        \"dateCreate\": \"2026-10-15T14:28:07+00:00\",\n        \"dateExpire\": \"2026-10-16T14:28:07+00:00\",\n        \"requireApproval\": false,\n        \"url\": \"https:\u002F\u002Fb24.to\u002Fgi\u002Fa1b2c3d4e5-Kp7rVx2mNq9sTb4H?IM_DIALOG=chat42&name=Alex\",\n        \"name\": \"+12025550123\"\n      },\n      \"phone\": \"+12025550123\"\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].extra` is not accepted. Accepted: phone, 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 `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 |\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, or a chat of this type does not accept guests — for example, a collab. 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 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.\n\n**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.\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 email](\u002Fdocs\u002Fchats\u002Fsharing\u002Finvite-email)\n- [Get a guest link](\u002Fdocs\u002Fchats\u002Fsharing\u002Fguest-link)\n- [Links and guests](\u002Fdocs\u002Fchats\u002Fsharing)\n","2026-10-15",{},1794739554209]