For AI agents: markdown of this page — /docs-content-en/entities/crm-forms/embedding-update.md documentation index — /llms.txt

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
Parameterid (path) Typenumber Requiredyes DescriptionPositive form ID from List forms

Request fields (body)

Example settings: click.settings.button.text, auto.settings.delay.

Get updatedTime from Get form 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.

Field Type Required Description
FieldupdatedTime Typestring Requiredyes DescriptionCurrent form version from GET /v1/crm-forms/:id
Fieldclick.settings.type Typestring / null Requiredno Descriptionpopup, panel
Fieldclick.settings.position Typestring / null Requiredno Descriptionleft, center, right
Fieldclick.settings.vertical Typestring / null Requiredno Descriptionbottom, top
Fieldauto.settings.type Typestring / null Requiredno Descriptionpopup, panel
Fieldauto.settings.position Typestring / null Requiredno Descriptionleft, center, right
Fieldauto.settings.vertical Typestring / null Requiredno Descriptionbottom, top
Fieldclick.settings.button.use Typeboolean / null Requiredno DescriptionUse the generated button
Fieldclick.settings.button.text Typestring / null Requiredno DescriptionButton caption
Fieldclick.settings.button.font Typestring / null Requiredno Descriptionmodern, classic, elegant
Fieldclick.settings.button.align Typestring / null Requiredno Descriptioninline, left, center, right
Fieldclick.settings.button.plain Typeboolean / null Requiredno DescriptionPlain button style
Fieldclick.settings.button.rounded Typeboolean / null Requiredno DescriptionRounded button corners
Fieldclick.settings.button.outlined Typeboolean / null Requiredno DescriptionOutlined button
Fieldclick.settings.button.decoration Typestring / null Requiredno DescriptionDecoration, for example dotted, solid, or an empty string
Fieldclick.settings.button.color.text Typestring / null Requiredno DescriptionText color. Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Fieldclick.settings.button.color.textHover Typestring / null Requiredno DescriptionText color on hover. Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Fieldclick.settings.button.color.background Typestring / null Requiredno DescriptionBackground color. Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Fieldclick.settings.button.color.backgroundHover Typestring / null Requiredno DescriptionBackground color on hover. Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
Fieldauto.settings.delay Typeinteger / null Requiredno DescriptionSeconds: 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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionEmbedding settings as returned by Bitrix24 after the write, or {id} if the additional read fails
Fielddata.id Typenumber DescriptionForm ID when the additional read fails
Fieldmeta.warnings Typeobject[] DescriptionA 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
Fieldmeta.redacted Typestring[] DescriptionPaths with connection credentials replaced. Such a response is not a complete configuration for saving back
Fielddata.formActive Typeboolean DescriptionWhether the form is active
Fielddata.resourcesReady Typeboolean DescriptionWhether form resources are ready
Fielddata.publicUrl Typestring DescriptionPublic form URL, including its public signature
Fielddata.inline Typeobject DescriptionForm embedded in the page
Fielddata.click Typeobject DescriptionForm opened on click
Fielddata.auto Typeobject DescriptionForm opened after a delay
Fielddata.<variant>.code Typestring / null DescriptionHTML embed code, or null when resources are not ready
Fielddata.<variant>.previewUrl Typestring DescriptionPreview URL when supplied. Missing fields and null values are preserved
Fielddata.<variant>.settings Typeobject / null DescriptionCurrent settings as returned by Bitrix24, including null
Fielddata.<variant>.options Typeobject / null DescriptionAllowed values returned by Bitrix24, including null
Fielddata.<variant>.options.type Typestring[] Descriptionpopup, panel
Fielddata.<variant>.options.position Typestring[] Descriptionleft, center, right
Fielddata.<variant>.options.vertical Typestring[] Descriptionbottom, top
Fielddata.click.options.button.font Typestring[] Descriptionmodern, classic, elegant
Fielddata.click.options.button.align Typestring[] Descriptioninline, left, center, right
Fielddata.auto.options.delay Typenumber[] Description3, 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": "<script data-b24-form=\"inline/59/p4yyaj\" data-b24-form-telemetry-sign=\"DUMMY_PUBLIC_SIGNATURE\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn.example.com/b13743910/crm/form/loader_59.js');\n</script>",
      "previewUrl": "https://example.bitrix24.com/pub/form/59_probe/p4yyaj/?view=preview&preview=inline",
      "settings": null,
      "options": null
    },
    "click": {
      "code": "<script data-b24-form=\"click/59/p4yyaj\" data-b24-form-telemetry-sign=\"DUMMY_PUBLIC_SIGNATURE\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn.example.com/b13743910/crm/form/loader_59.js');\n</script>",
      "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": "<script data-b24-form=\"auto/59/p4yyaj\" data-b24-form-telemetry-sign=\"DUMMY_PUBLIC_SIGNATURE\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn.example.com/b13743910/crm/form/loader_59.js');\n</script>",
      "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
HTTP400 CodeINVALID_PARAMS DescriptionInvalid form ID or request structure
HTTP400 CodeINVALID_PARAMS DescriptionUnknown query parameter or invalid request structure
HTTP400 CodeINVALID_PARAMS DescriptionupdatedTime is missing
HTTP400 CodeINVALID_PARAMS DescriptionBitrix24 rejected a setting. Field diagnostics are returned in error.validation and the original code in error.b24Code
HTTP409 CodeCRM_FORM_REST_NOT_ENABLED DescriptionCRM form REST methods are disabled on the Bitrix24 account. The original code for the missing method is in error.b24Code
HTTP403 CodeBITRIX_INSUFFICIENT_SCOPE DescriptionThe Bitrix24 token lacks the required scope. The original code is in error.b24Code
HTTP404 CodeENTITY_NOT_FOUND DescriptionForm not found
HTTP402 CodeCRM_FORM_WRITE_RESTRICTED DescriptionThe Bitrix24 plan (free or demo) does not allow writing CRM forms
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user lacks access permissions
HTTP403 CodeCRM_FORM_SYSTEM_IMMUTABLE DescriptionThe form is a system form — system: true in the form list
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionAPI key is read-only
HTTP409 CodeCRM_FORM_VERSION_MISMATCH DescriptionThe form was modified after the passed updatedTime. The current modification time is in error.currentUpdatedTime
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured credentials
HTTP500 CodeCRM_FORM_SIDE_EFFECT_FAILED DescriptionThe changes are already written, but a subsequent step on the Bitrix24 side failed. Read the form before retrying
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionInvalid embedding response

Errors from Bitrix24 include the original error.b24Code and field diagnostics in error.validation, when supplied. For common API errors, see Errors.

Known specifics

The embedding response does not include updatedTime. Before the next embedding or form update, read the form with Get form. 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