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

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
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 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
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 DescriptionCaption, up to 255 characters
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 DescriptionUp to 20 characters, 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

inline, code, previewUrl, options, publicUrl, formActive, and resourcesReady are read-only and cannot be sent in the request.

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 } = 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
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionComplete embedding settings
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 DescriptionHTML embed code, returned unchanged
Fielddata.<variant>.previewUrl Typestring DescriptionPreview URL, returned unchanged
Fielddata.<variant>.settings Typeobject / null DescriptionCurrent settings listed in Update embedding settings. inline has null
Fielddata.<variant>.options Typeobject / null DescriptionAllowed values for the variant settings. inline has 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": "MISSING_REQUIRED_FIELDS",
    "message": "updatedTime is required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionInvalid form ID or request structure
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown query parameter
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionupdatedTime is missing
HTTP400 CodeINVALID_PARAMS DescriptionUnsupported setting value, including auto.settings.delay=11. Field diagnostics are returned in error.validation
HTTP404 CodeENTITY_NOT_FOUND DescriptionForm not found
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionUser lacks access
HTTP403 CodeCRM_FORM_ACCESS_DENIED DescriptionForm access is denied
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionAPI key is read-only
HTTP409 CodeCRM_FORM_CONFLICT DescriptionForm version has changed. Read the form again and retry with its current updatedTime
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured credentials
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionInvalid embedding response

For common API errors, see Errors.

Known specifics

Updating embedding settings changes the form's updatedTime. The embedding response does not contain the new version. Read Get form again before the next embedding or form update.

See also