For AI agents: markdown of this page — /docs-content-en/apps/placements.md documentation index — /llms.txt

Placements

A placement is a point in the Bitrix24 interface where your application opens: a tab in a deal card, a left-menu item, a button on a list toolbar, a panel in a chat. Binding registers the application at such a point on the account, unbinding removes it from there.

Scope: placement | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key (application authorization key)

Bound placements

GET /v1/placements

Returns the placements that are listed as bound for the application. When a session token is passed together with the application key, Vibecode additionally reconciles this list with the Bitrix24 account.

Call preconditions — what is required before binding.

Examples

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/placements \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/placements', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log('Confirmed by the account:', data.handlers)

Response fields

Field Type Description
success boolean Always true on success
data.placements string[] Placement codes bound by the application
data.appId string Application identifier. List of applications — GET /v1/apps
data.appTitle string Application name
data.handlers array Handler data received from the account. The field is optional — it is returned only when a session token is passed
data.handlers[].placement string Placement code
data.handlers[].handler string Handler address registered on the account
data.handlers[].misbound boolean true when the handler is registered to the technical address of the application server. Such a placement will not pass authorization inside Bitrix24
data.handlers[].title string Placement caption on the account
data.handlers[].options array | object Placement settings. An empty array when there are no settings
data.handlers[].langAll object Placement captions by language. The key is the language code, the values are TITLE, DESCRIPTION, GROUP_NAME
warnings string[] Appears when at least one placement has misbound equal to true

Response example

A session token was passed and the account confirmed the tab in the deal card:

JSON 
{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU", "CRM_DEAL_DETAIL_TAB"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Sales dashboard",
    "handlers": [
      {
        "placement": "CRM_DEAL_DETAIL_TAB",
        "handler": "https://example.com/tab",
        "misbound": false,
        "title": "Deal documents",
        "options": [],
        "langAll": {
          "en": { "TITLE": "Deal documents", "DESCRIPTION": "", "GROUP_NAME": "" },
          "ru": { "TITLE": "Deal documents", "DESCRIPTION": "", "GROUP_NAME": "" }
        }
      }
    ]
  }
}

The account returned none of the bound codes — handlers is returned empty:

JSON 
{
  "success": true,
  "data": {
    "placements": ["LEFT_MENU"],
    "appId": "3d5f7a91-2b4c-4e8f-9a01-6c7d8e9f0a1b",
    "appTitle": "Sales dashboard",
    "handlers": []
  }
}

Error response example

400 — the request was made with a personal key:

JSON 
{
  "success": false,
  "error": {
    "code": "OAUTH_APP_REQUIRED",
    "message": "Placement management is only available for OAuth app keys"
  }
}

Errors

HTTP Code Description
400 OAUTH_APP_REQUIRED The request was made with a personal vibe_api_ key
401 MISSING_API_KEY The X-Api-Key header was not passed
401 INVALID_API_KEY Invalid key
404 APP_NOT_FOUND No application is linked to the key

Full list of common API errors — Errors.

Known specifics

  • An empty handlers with a non-empty placements indicates a discrepancy. The placement is listed as bound in Vibecode, but the account did not return it: there is no such placement on the Bitrix24 side. It is restored by calling Bind a placement again.
  • The handlers field may be absent even when a session token is passed — when the application has no bound placements or the response from the account could not be obtained. The absence of the field does not mean there are no placements — check against data.placements.
  • A placement with misbound equal to true is fixed by binding it again. A call to Bind a placement replaces the technical address of the application server with the platform handler address.

See also