## Update form embedding settings `PATCH /v1/crm-forms/:id/embedding` Update the settings for showing a form on a website on click and after a delay. Omitted settings remain unchanged. ## Parameters | Parameter | Type | Required | Description | |---|---|---|---| | `id` (path) | number | yes | Positive form ID from [List forms](/docs/entities/crm-forms/list) | ## Request fields (body) Example settings: `click.settings.button.text`, `auto.settings.delay`. Get `updatedTime` from [Get form](/docs/entities/crm-forms/get) before the request. Replace `YOUR_UPDATED_TIME` in the examples with that value. Send settings flat at the root of the body, as in the examples, or use `{updatedTime, fields: {click: {...}, auto: {...}}}`. `fields` must be an object when used as a wrapper. Do not mix wrapped settings with settings at the root. The table gives examples of settings, not an exhaustive list. Bitrix24 validates property paths, values and whether `null` can clear a setting. Read current options from [Get form embedding codes](/docs/entities/crm-forms/embedding). | Field | Type | Required | Description | |---|---|---|---| | `updatedTime` | string | yes | Current form version from `GET /v1/crm-forms/:id` | | `click.settings.type` | string / null | no | `popup`, `panel` | | `click.settings.position` | string / null | no | `left`, `center`, `right` | | `click.settings.vertical` | string / null | no | `bottom`, `top` | | `auto.settings.type` | string / null | no | `popup`, `panel` | | `auto.settings.position` | string / null | no | `left`, `center`, `right` | | `auto.settings.vertical` | string / null | no | `bottom`, `top` | | `click.settings.button.use` | boolean / null | no | Use the generated button | | `click.settings.button.text` | string / null | no | Button caption | | `click.settings.button.font` | string / null | no | `modern`, `classic`, `elegant` | | `click.settings.button.align` | string / null | no | `inline`, `left`, `center`, `right` | | `click.settings.button.plain` | boolean / null | no | Plain button style | | `click.settings.button.rounded` | boolean / null | no | Rounded button corners | | `click.settings.button.outlined` | boolean / null | no | Outlined button | | `click.settings.button.decoration` | string / null | no | Decoration, for example `dotted`, `solid`, or an empty string | | `click.settings.button.color.text` | string / null | no | Text color. Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` | | `click.settings.button.color.textHover` | string / null | no | Text color on hover. Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` | | `click.settings.button.color.background` | string / null | no | Background color. Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` | | `click.settings.button.color.backgroundHover` | string / null | no | Background color on hover. Hex: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` | | `auto.settings.delay` | integer / null | no | Seconds: `3`, `5`, `7`, `10`, `15`, `20`, `25`, `30`, `40`, `60`, `120` | Bitrix24 decides which properties can be written. Embedding response fields do not define a local list of writable settings. ## Examples ### curl — personal key ```bash curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-forms/59/embedding" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "updatedTime": "YOUR_UPDATED_TIME", "auto": { "settings": { "delay": 10 } }, "click": { "settings": { "button": { "text": "Write us" } } } }' ``` ### curl — OAuth application ```bash curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-forms/59/embedding" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "updatedTime": "YOUR_UPDATED_TIME", "auto": { "settings": { "delay": 10 } }, "click": { "settings": { "button": { "text": "Write us" } } } }' ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/59/embedding', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ updatedTime: 'YOUR_UPDATED_TIME', auto: { settings: { delay: 10 } }, click: { settings: { button: { text: 'Write us' } } }, }), }) const { success, data, meta } = await res.json() ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/59/embedding', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ updatedTime: 'YOUR_UPDATED_TIME', auto: { settings: { delay: 10 } }, click: { settings: { button: { text: 'Write us' } } }, }), }) const { success, data, meta } = await res.json() ``` ## Response fields | Field | Type | Description | |---|---|---| | `success` | boolean | `true` on success | | `data` | object | Embedding settings as returned by Bitrix24 after the write, or `{id}` if the additional read fails | | `data.id` | number | Form ID when the additional read fails | | `meta.warnings` | object[] | A confirmed write remains successful if the additional read fails. `CRM_FORM_READBACK_FAILED` instructs the client to GET the form and embedding before another change, without repeating the write | | `meta.redacted` | string[] | Paths with connection credentials replaced. Such a response is not a complete configuration for saving back | | `data.formActive` | boolean | Whether the form is active | | `data.resourcesReady` | boolean | Whether form resources are ready | | `data.publicUrl` | string | Public form URL, including its public signature | | `data.inline` | object | Form embedded in the page | | `data.click` | object | Form opened on click | | `data.auto` | object | Form opened after a delay | | `data..code` | string / null | HTML embed code, or `null` when resources are not ready | | `data..previewUrl` | string | Preview URL when supplied. Missing fields and `null` values are preserved | | `data..settings` | object / null | Current settings as returned by Bitrix24, including `null` | | `data..options` | object / null | Allowed values returned by Bitrix24, including `null` | | `data..options.type` | string[] | `popup`, `panel` | | `data..options.position` | string[] | `left`, `center`, `right` | | `data..options.vertical` | string[] | `bottom`, `top` | | `data.click.options.button.font` | string[] | `modern`, `classic`, `elegant` | | `data.click.options.button.align` | string[] | `inline`, `left`, `center`, `right` | | `data.auto.options.delay` | number[] | `3`, `5`, `7`, `10`, `15`, `20`, `25`, `30`, `40`, `60`, `120` | ## Response example Public domains and signatures in this example are placeholders. ```json { "success": true, "data": { "formActive": true, "resourcesReady": true, "publicUrl": "https://example.bitrix24.com/crm_form_nfby7/?telemetry_sign=DUMMY_PUBLIC_SIGNATURE", "inline": { "code": "", "previewUrl": "https://example.bitrix24.com/pub/form/59_probe/p4yyaj/?view=preview&preview=inline", "settings": null, "options": null }, "click": { "code": "", "previewUrl": "https://example.bitrix24.com/pub/form/59_probe/p4yyaj/?view=preview&preview=click", "settings": { "type": "panel", "position": "right", "vertical": "bottom", "button": { "use": true, "text": "Write us", "font": null, "align": null, "plain": false, "rounded": false, "outlined": false, "decoration": null, "color": { "text": null, "textHover": null, "background": null, "backgroundHover": null } } }, "options": { "type": [ "popup", "panel" ], "position": [ "left", "center", "right" ], "vertical": [ "bottom", "top" ], "button": { "font": [ "modern", "classic", "elegant" ], "align": [ "inline", "left", "center", "right" ] } } }, "auto": { "code": "", "previewUrl": "https://example.bitrix24.com/pub/form/59_probe/p4yyaj/?view=preview&preview=auto", "settings": { "type": "popup", "position": "right", "vertical": "bottom", "delay": 10 }, "options": { "type": [ "popup", "panel" ], "position": [ "left", "center", "right" ], "vertical": [ "bottom", "top" ], "delay": [ 3, 5, 7, 10, 15, 20, 25, 30, 40, 60, 120 ] } } } } ``` ## Error response example 400 — `updatedTime` is missing: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "updatedTime from GET /v1/crm-forms/:id is required" } } ``` ## Errors | HTTP | Code | Description | |---|---|---| | 400 | `INVALID_PARAMS` | Invalid form ID or request structure | | 400 | `INVALID_PARAMS` | Unknown query parameter or invalid request structure | | 400 | `INVALID_PARAMS` | `updatedTime` is missing | | 400 | `INVALID_PARAMS` | Bitrix24 rejected a setting. Field diagnostics are returned in `error.validation` and the original code in `error.b24Code` | | 409 | `CRM_FORM_REST_NOT_ENABLED` | CRM form REST methods are disabled on the Bitrix24 account. The original code for the missing method is in `error.b24Code` | | 403 | `BITRIX_INSUFFICIENT_SCOPE` | The Bitrix24 token lacks the required scope. The original code is in `error.b24Code` | | 404 | `ENTITY_NOT_FOUND` | Form not found | | 402 | `CRM_FORM_WRITE_RESTRICTED` | The Bitrix24 plan (free or demo) does not allow writing CRM forms | | 403 | `SCOPE_DENIED` | API key lacks the `crm` scope | | 403 | `BITRIX_ACCESS_DENIED` | The user lacks access permissions | | 403 | `CRM_FORM_SYSTEM_IMMUTABLE` | The form is a system form — `system: true` in the [form list](/docs/entities/crm-forms/list) | | 403 | `WRITE_BLOCKED_READONLY_KEY` | API key is read-only | | 409 | `CRM_FORM_VERSION_MISMATCH` | The form was modified after the passed `updatedTime`. The current modification time is in `error.currentUpdatedTime` | | 401 | `TOKEN_MISSING` | API key has no configured credentials | | 500 | `CRM_FORM_SIDE_EFFECT_FAILED` | The changes are already written, but a subsequent step on the Bitrix24 side failed. Read the form before retrying | | 502 | `BITRIX_UNAVAILABLE` | Invalid embedding response | Errors from Bitrix24 include the original `error.b24Code` and field diagnostics in `error.validation`, when supplied. For common API errors, see [Errors](/docs/errors). ## Known specifics The embedding response does not include `updatedTime`. Before the next embedding or form update, read the form with [Get form](/docs/entities/crm-forms/get). If `meta.warnings` reports a failed read, the write has already succeeded: do not repeat it. Re-read the form and embedding. Embedding objects retain their original fields. A `resourcesReady: false` or `code: null` supplied by Bitrix24 remains a successful response. Only current connection credentials are replaced, with their paths listed in `meta.redacted`. ## See also - [Get form](/docs/entities/crm-forms/get) - [Get form embedding codes](/docs/entities/crm-forms/embedding)