Block Editing Item LANDING_BLOCK_ and LANDING_BLOCK_*
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Scope:
landing
The LANDING_BLOCK_<CODE> and LANDING_BLOCK_* widgets add an application item to the block actions menu in the page editor.
Use them when the application works with a single block rather than the whole page. For example, it:
- translates the block text and writes the translation back
- checks an image link in the block
If the action applies to the whole site or page, for example, checks meta tags, use LANDING_SETTINGS.
The embedding location is registered with the landing.repo.bind method, not placement.bind. The method works only in the application context; you cannot register the embedding location via a webhook.
The embedding location will not be displayed in the interface until the application installation is complete. Check the application installation
Where the Widget is Integrated
|
Embedding Location Code |
Location |
|
|
Item in the actions menu of blocks of one kind. For a standard block, For a block that the application registered with the landing.repo.register method, |
|
|
Item in the actions menu of all blocks |
The case of the characters in the code does not matter.
Where to Find It in the Interface
Open the page in edit mode and hover over the block. A More button appears to the right of the Edit button — the application item is in its dropdown list. The item label is the TITLE value from the registration or, if it is empty, the application name. If the application registered both <CODE> and * for a block, the list shows both items.
The item is visible to everyone who opens the page in the editor: permissions to modify the block are not checked when the item is displayed. If the application action modifies the block, check permissions in the handler.
What the Handler Receives
Data is sent in a POST request: some parameters come in the handler URL query string, the rest in the request body
Array
(
[DOMAIN] => example.bitrix24.com
[PROTOCOL] => 1
[LANG] => de
[APP_SID] => 0123456789abcdef0123456789abcdef
[APPLICATION_SCOPE] => crm,placement,landing
[APPLICATION_TOKEN] => xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
[AUTH_ID] => 6061e72600631fcd00005a4b00000001f0f1076700000000f69dd5fc643d9ce2fdbc1
[AUTH_EXPIRES] => 3600
[REFRESH_ID] => 50e00aa340631fcd00005a4b00000001f0f1071111116580a5b83c2de639ef28c12
[SERVER_ENDPOINT] => https://oauth.bitrix24.info/rest/
[member_id] => abcdef1234567890abcdef1234567890
[status] => F
[PLACEMENT] => LANDING_BLOCK_*
[PLACEMENT_OPTIONS] => {"ID":"996","CODE":"43.4.cover_with_price_text_button_bgimg","LID":"30","URI":"\/sites\/site\/12\/view\/30\/"}
)
Required parameters are marked with *
Parameters in the Handler URL Query String
|
Parameter |
Description |
|
DOMAIN* |
The Bitrix24 address where the widget handler was invoked |
|
PROTOCOL* |
Secure or non-secure HTTP protocol:
|
|
LANG* |
The user interface language of Bitrix24 that invoked the widget. You can localize the interface language in your widget based on this value |
|
APP_SID* |
Application session identifier. Bitrix24 generates a new one each time the widget is rendered and uses it to link the js library with the application environment |
Parameters in the POST Request Body
|
Parameter |
Description |
|
AUTH_ID |
Authorization token OAuth 2 issued for the user who invoked the widget. Can be used for REST API calls on behalf of this user |
|
AUTH_EXPIRES |
Time in seconds after which the authorization token will become invalid |
|
REFRESH_ID |
Refresh token OAuth 2 issued for the user who invoked the widget. Can be used to refresh the authorization token on behalf of this user |
|
SERVER_ENDPOINT* |
Address of the Bitrix24 authorization server needed to refresh OAuth 2 tokens |
|
APPLICATION_TOKEN* |
Application token. The same value is passed in the |
|
APPLICATION_SCOPE* |
List of scopes granted to the application, separated by commas. Shows which REST API methods are available with the authorization token received |
|
member_id* |
Unique string identifier of Bitrix24 where the widget handler was invoked. |
|
status |
Type of application that registered the handler for this widget. Accepts values:
|
|
PLACEMENT* |
The placement code. You can use the same handler URL for all your widgets. The value that Bitrix24 will report in the |
|
PLACEMENT_OPTIONS |
Additional data in the form of a JSON string that defines the context of the widget execution. For example, this could be an array containing the numeric identifier of the CRM object in the detail form where the widget handler was invoked, etc. The |
Bitrix24 adds a URI key to PLACEMENT_OPTIONS — the path with the query string of the page from which the widget was opened. It arrives for any placement, along with the keys of that placement itself. The key is absent if the browser did not send the Referer header or if the widget was opened from a page on a different domain.
How to Parse the Call Context
PLACEMENT_OPTIONS arrives as a JSON string, not as an array: parse it on the handler side before use. The set of keys is specific to each placement and is described in the PLACEMENT_OPTIONS section of this page.
$placement = $_POST['PLACEMENT'] ?? '';
$options = json_decode($_POST['PLACEMENT_OPTIONS'] ?? '{}', true);
options = json.loads(request.form.get("PLACEMENT_OPTIONS", "{}") or "{}")
In B24JsSDK, there is no need to parse the string: the $b24.placement.options property returns a ready object, and $b24.placement.placement returns the placement code.
What the Handler Must Return
The handler responds with a regular HTML page — Bitrix24 displays it in a frame in place of the widget. The page must allow embedding: if the application server sends the X-Frame-Options or Content-Security-Policy headers that prohibit framing, an empty area remains in place of the widget. How to fix it is described in the article Site Does Not Allow Connection.
The part of the code after LANDING_BLOCK_ in the PLACEMENT parameter arrives in lowercase: LANDING_BLOCK_*, LANDING_BLOCK_04.1.one_col_fix_with_title, or LANDING_BLOCK_repo_1132.
PLACEMENT_OPTIONS
The value of PLACEMENT_OPTIONS is passed as a JSON string with the context of the call.
For LANDING_BLOCK_<CODE> and LANDING_BLOCK_*, the same keys are passed in the context:
|
Key |
Description |
|
ID |
Block identifier on the page. It is accepted by the methods of the Blocks section, for example, landing.block.getbyid. This is not the block identifier in the repository from the |
|
CODE |
Symbolic code of the block, for example, |
|
LID |
Identifier of the page where the block is opened |
|
URI |
Path with the query string of the page from which the widget is opened. If the page address cannot be determined, the key is not passed |
Code Examples
How to Use Examples in Documentation
The examples register an item for the standard block 04.1.one_col_fix_with_title. To make the item appear for all blocks, pass LANDING_BLOCK_* in PLACEMENT; the other fields stay the same.
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"fields": {
"PLACEMENT": "LANDING_BLOCK_04.1.one_col_fix_with_title",
"PLACEMENT_HANDLER": "https://your-domain.com/widgets/landing-block-handler.php",
"TITLE": "My Widget for the Block"
},
"auth": "**put_access_token_here**"
}' \
https://**put_your_bitrix24_address**/rest/landing.repo.bind
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
try {
const response = await $b24.actions.v2.call.make<boolean>({
method: 'landing.repo.bind',
params: {
fields: {
PLACEMENT: 'LANDING_BLOCK_04.1.one_col_fix_with_title',
PLACEMENT_HANDLER: 'https://your-domain.com/widgets/landing-block-handler.php',
TITLE: 'My Widget for the Block',
},
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Binding result:', result)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function bindLandingBlock() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'landing.repo.bind',
params: {
fields: {
PLACEMENT: 'LANDING_BLOCK_04.1.one_col_fix_with_title',
PLACEMENT_HANDLER: 'https://your-domain.com/widgets/landing-block-handler.php',
TITLE: 'My Widget for the Block',
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Binding result:', result)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', bindLandingBlock)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.landing.repo.bind(
fields={
"PLACEMENT": "LANDING_BLOCK_04.1.one_col_fix_with_title",
"PLACEMENT_HANDLER": "https://your-domain.com/widgets/landing-block-handler.php",
"TITLE": "My Widget for the Block",
},
).response
result = bitrix_response.result
print(result)
except BitrixAPIError as error:
print(
"Bitrix API error",
f"error: {error.error}",
f"error_description: {error.error_description}",
sep="\n",
)
except BitrixSDKException as error:
print(f"Bitrix SDK error: {error.message}")
except Exception as error:
print(f"Unexpected error: {error}")
try {
$response = $b24Service
->core
->call(
'landing.repo.bind',
[
'fields' => [
'PLACEMENT' => 'LANDING_BLOCK_04.1.one_col_fix_with_title',
'PLACEMENT_HANDLER' => 'https://your-domain.com/widgets/landing-block-handler.php',
'TITLE' => 'My Widget for the Block',
],
]
);
$result = $response->getResponseData()->getResult();
echo 'Success: ' . var_export($result, true);
} catch (Throwable $e) {
error_log($e->getMessage());
echo 'Error binding landing block: ' . $e->getMessage();
}
BX24.callMethod(
'landing.repo.bind',
{
fields: {
PLACEMENT: 'LANDING_BLOCK_04.1.one_col_fix_with_title',
PLACEMENT_HANDLER: 'https://your-domain.com/widgets/landing-block-handler.php',
TITLE: 'My Widget for the Block'
}
},
function(result)
{
if (result.error()) {
console.error(result.error());
} else {
console.info(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'landing.repo.bind',
[
'fields' => [
'PLACEMENT' => 'LANDING_BLOCK_04.1.one_col_fix_with_title',
'PLACEMENT_HANDLER' => 'https://your-domain.com/widgets/landing-block-handler.php',
'TITLE' => 'My Widget for the Block',
],
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "landing.repo.bind", b24.Params{
"fields": b24.Params{
"PLACEMENT": "LANDING_BLOCK_04.1.one_col_fix_with_title",
"PLACEMENT_HANDLER": "https://your-domain.com/widgets/landing-block-handler.php",
"TITLE": "My Widget for the Block",
},
})
if err != nil {
return fmt.Errorf("landing.repo.bind: %w", err)
}
// The response arrives as json.RawMessage. On success, result = true.
// The response shape is described on the landing.repo.bind method page.
fmt.Printf("%s\n", res.Result)
How to Update a Block from the Application
If the application has changed the block content, for example, with the landing.block.updatenodes method, the editor keeps showing the old version. To redraw the block, call the refreshBlock command of the BX24.placement.call method from the widget frame.
The command works only inside an open LANDING_BLOCK_<CODE> or LANDING_BLOCK_* widget: it is executed by the page editor, and there is no separate REST method for it.
Pass id to the command — the block identifier on the page, as a string or a number. Take it from the ID key in PLACEMENT_OPTIONS.
The callback function fires after the editor reloads the block. If there is no block with this id on the open page, the command does nothing and the callback function is not called.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
// Block ID from PLACEMENT_OPTIONS.ID
const options = $b24.placement.options as { ID: string }
await $b24.placement.call('refreshBlock', { id: Number(options.ID) })
console.info('Block refreshed')
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', async () => {
const $b24 = await B24Js.initializeB24Frame()
// Block ID from PLACEMENT_OPTIONS.ID
const blockId = Number($b24.placement.options.ID)
await $b24.placement.call('refreshBlock', { id: blockId })
console.info('Block refreshed')
})
</script>
BX24.ready(function () {
BX24.init(function () {
// Block ID from PLACEMENT_OPTIONS.ID
var blockId = Number(BX24.placement.info().options.ID);
BX24.placement.call('refreshBlock', { id: blockId }, function () {
console.log('Block refreshed');
});
});
});
Continue Learning
- Embedding Locations in the Sites Section: Overview of Methods
- Register an Embedding Location landing.repo.bind
- Remove Embedding Placement landing.repo.unbind
- Menu Item in Site Settings and LANDING_SETTINGS Page
- Update Nodes of the Block landing.block.updatenodes
- Get a List of Blocks from the Repository landing.block.getrepository
- Add a Custom Block to the Repository landing.repo.register
- Call the Registered Interface Command BX24.placement.call
- Methods of BX24 SDK for Widgets