## Update form embedding settings `PATCH /v1/crm-forms/:id/embedding` Updates individual click and automatic display settings and returns the complete embedding settings after reading them again. Send nested `click.settings` and `auto.settings` objects without a `fields` wrapper. 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) immediately before the request. Replace `YOUR_UPDATED_TIME` in the examples with that value. Every setting below is optional. Send `null` for an individual setting to clear its saved value. Clear settings individually, not an entire `click`, `auto`, `settings`, `button`, or `color` object. | 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 | Caption, up to 255 characters | | `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 | Up to 20 characters, 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` | `inline`, `code`, `previewUrl`, `options`, `publicUrl`, `formActive`, and `resourcesReady` are read-only and cannot be sent in the request. ## 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 } = 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 } = await res.json() ``` ## Response fields | Field | Type | Description | |---|---|---| | `success` | boolean | `true` on success | | `data` | object | Complete embedding settings | | `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 | HTML embed code, returned unchanged | | `data..previewUrl` | string | Preview URL, returned unchanged | | `data..settings` | object / null | Current settings listed in [Update embedding settings](/docs/entities/crm-forms/embedding-update). `inline` has `null` | | `data..options` | object / null | Allowed values for the variant settings. `inline` has `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": "MISSING_REQUIRED_FIELDS", "message": "updatedTime is required" } } ``` ## Errors | HTTP | Code | Description | |---|---|---| | 400 | `INVALID_PARAMS` | Invalid form ID or request structure | | 400 | `UNKNOWN_FILTER_FIELD` | Unknown query parameter | | 400 | `MISSING_REQUIRED_FIELDS` | `updatedTime` is missing | | 400 | `INVALID_PARAMS` | Unsupported setting value, including `auto.settings.delay=11`. Field diagnostics are returned in `error.validation` | | 404 | `ENTITY_NOT_FOUND` | Form not found | | 403 | `SCOPE_DENIED` | API key lacks the `crm` scope | | 403 | `BITRIX_ACCESS_DENIED` | User lacks access | | 403 | `CRM_FORM_ACCESS_DENIED` | Form access is denied | | 403 | `WRITE_BLOCKED_READONLY_KEY` | API key is read-only | | 409 | `CRM_FORM_CONFLICT` | Form version has changed. Read the form again and retry with its current `updatedTime` | | 401 | `TOKEN_MISSING` | API key has no configured credentials | | 502 | `BITRIX_UNAVAILABLE` | Invalid embedding response | For common API errors, see [Errors](/docs/errors). ## Known specifics Updating embedding settings changes the form's `updatedTime`. The embedding response does not contain the new version. Read [Get form](/docs/entities/crm-forms/get) again before the next embedding or form update. ## See also - [Get form](/docs/entities/crm-forms/get) - [Get form embedding codes](/docs/entities/crm-forms/embedding)