Development of applications for the Bitrix24 marketplace

Development of Applications for Bitrix24 Marketplace

An app for Bitrix24 marketplace — not just a web service with OAuth. It's a product that must work in iframe inside corporate portal of tens of thousands of companies, on different tariff plans, with different module sets and user rights. Most problems arise not during development, but after publication — when it turns out half the users lack needed rights, REST method unavailable on "Basic" plan.

Application Types in Bitrix24 Ecosystem

Before development, important to choose correct application type:

Embedded applications (embed) — work in iframe, integrate into Bitrix24 interface via placement API. Integration points: CRM_LEAD_DETAIL_TAB, CRM_DEAL_DETAIL_TAB, CRM_CONTACT_DETAIL_TAB, CALL_LIST, TASKS_TASK_VIEW_TAB, USER_PROFILE_MENU and dozens more. Most common type.

Widgets — embed in specific interface areas via BX24.placement.call(). Useful for small actions: button in CRM card, panel in chat.

Apps with own interface — open in separate tab or modal window, use REST API fully in own logic. More UX freedom, but user "exits" B24 context.

Bots and chat apps — work via imbot.* and imsetting.* methods, have own event handler.

Authorization Mechanism: OAuth 2.0 + Server-to-Server

Bitrix24 app authorization works via OAuth 2.0 with authorization code. Flow on first run:

1. User installs app → Bitrix24 redirects to redirect_uri with code
2. App exchanges code for access_token and refresh_token via https://oauth.bitrix.info/oauth/token/
3. access_token lives 1 hour, refresh_token — 180 days
4. App stores tokens in own database, binding them to member_id (unique portal identifier)

For server-to-server interaction (without user participation) you request rights from application, not user. Works via OAuth with grant_type=client_credentials — available only for "Application" type apps, not "Widget".

Critical point: use member_id as tenant identifier if your app is multi-tenant. All database data must be partitioned by member_id, otherwise one company's data leaks to another.

REST API: Working with Bitrix24 Data

Bitrix24 REST API — not classical REST. Methods called via POST to https://{portal}.bitrix24.ru/rest/{method} with body as form-data or JSON. Pagination works via start (offset), limit fixed — 50 records. To get all records need loop with next from response.

Most used method groups:

• crm.lead., crm.deal., crm.contact., crm.company. — CRM work
• tasks.task.*, task.item.list — tasks
• disk.folder., disk.file. — files and drives
• im.message.add, imbot.message.add — messages
• user.get, user.search — users
• placement.bind — register integration points

Batching: can send up to 50 requests simultaneously via batch method. Critical for performance — don't make 50 separate HTTP requests where you can make one batched.

POST /rest/batch
{
  "halt": 0,
  "cmd": {
    "get_deal": "crm.deal.get?id=123",
    "get_contact": "crm.contact.get?id=456",
    "get_company": "crm.company.get?id=789"
  }
}

Webhooks and Events

App can subscribe to portal events via event.bind. On event Bitrix24 makes POST request to app's handler URL. Important details:

• Handler must respond within 5 seconds, otherwise Bitrix24 considers delivery failed
• After 3 consecutive failed deliveries — handler auto-unbinded
• For heavy processing must use queue: receive webhook, put in queue, respond 200, process async

Available events: ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKUPDATE, ONIMMESSAGECHAT, ONUSERADD and hundreds others. Full list depends on tariff and installed portal modules.

Placements — How App Embeds in Interface

Placement registered on app install via placement.bind call. Placement tied to specific interface point and passes context to app: entity ID, type, user rights.

// In app iframe:
BX24.placement.getInterface(function(data) {
    // data contains context: entityType, entityId etc.
    console.log(data);
});

To work with BX24 JS SDK need connect //api.bitrix24.com/api/v1/ and call BX24.init() before any API calls. In iframe environment cookies work with restrictions — need use localStorage or pass token via postMessage.

Working with Tariff Limitations

Main pain of marketplace apps: REST methods available not on all tariffs. Methods crm.* exist only from certain plans, telephony.* — only with telephony connected, tasks.* can be unavailable with disabled module.

Correct approach — on install check availability of needed methods via app.info and profile, explicitly tell user if their tariff doesn't support app functionality. Falling with unhandled 403 on method call — unacceptable.

App Data Storage

Bitrix24 provides own storage for apps via app.option.set / app.option.get methods — simple key-value storage on portal side, ~32KB value limit. For serious data app must have own database.

For user settings: user.option.set / user.option.get — per-user settings storage on Bitrix24 side.

Development Timeline

App Infrastructure

App must be accessible via HTTPS with valid SSL certificate — Bitrix24 doesn't work with HTTP or self-signed certs. For production: separate domain, horizontal scaling capability (tokens stored in Redis/DB, not process memory), webhook handler monitoring.

Logging: all REST API calls, all incoming webhooks, all OAuth exchanges. When debugging incidents at customer this only way to understand what went wrong.