Bitrix24 Integration with Mobile App

Bitrix24 Integration with Mobile Application

Bitrix24 provides REST API via OAuth 2.0—a standard and well-documented integration method. Most methods work predictably, but there are nuances: request rate limits, different data formats in different plans, and non-obvious webhook behavior in certain events.

OAuth 2.0 and Tokens

Bitrix24 uses OAuth 2.0 Authorization Code Flow. The mobile application opens a WebView or SFSafariViewController / Chrome Custom Tabs with authorization URL:

https://{portal}.bitrix24.ru/oauth/authorize/?
  client_id={app_id}&
  response_type=code&
  redirect_uri={deeplink}

After authorization, you receive a code, exchanged for access_token and refresh_token. access_token lives 1 hour, refresh_token — 30 days. Token refresh uses standard grant_type=refresh_token. Store refresh_token in Keychain/Keystore.

Bitrix24 webhooks—a simplified version without OAuth. Incoming webhook—URL with token, through which the application calls API without user authorization. Convenient for server integration, risky if webhook URL is stored on mobile client (leak gives portal access).

Main API Methods

Working with deals:

// Retrofit
interface Bitrix24Api {
    @GET("crm.deal.list")
    suspend fun getDeals(
        @Query("auth") token: String,
        @Query("filter[STAGE_ID]") stageId: String,
        @Query("select[]") fields: List<String>,
        @Query("start") offset: Int
    ): Bitrix24ListResponse<Deal>
}

start — offset for pagination. Bitrix24 returns maximum 50 records at a time. Response contains next—next offset, total—total count. Multiple requests needed for full list.

Limit: 2 requests per second with OAuth, 2 per second for incoming webhook. For batch synchronization — use batch method: up to 50 methods in one HTTP request:

{
  "halt": 0,
  "cmd": {
    "get_deals": "crm.deal.list?filter[STAGE_ID]=NEW",
    "get_contacts": "crm.contact.list?filter[TYPE_ID]=CLIENT"
  }
}

Webhooks for Real-time Updates

Outgoing Bitrix24 webhook—POST to specified URL on event (deal change, new lead). Server receives, recognizes event, sends push notification to device.

Bitrix24 sends webhook with event fields, but not full object data—only ID and event type. Need additional crm.deal.get request to fetch current data. Adds 1-2 second delay from event to display in app.

Events most commonly needed: ONCRMDEALADD, ONCRMDEALUPDATE, ONCRMLEADADD, ONCRMACTIVITYADD. For tasks: ONTASKUPDATE, ONTASKADD.

Telephony and Calls

Bitrix24 registers calls via voximplant.infocall.startwithsound or telephony.call.attachbyqueue. For mobile app you can initiate click-to-call: telephony.externalcall.register creates call card in Bitrix24, links with client. After call — telephony.externalcall.finish with duration and result.

For VoIP directly in app—integrate with Voximplant (Bitrix24 partner) or Twilio via Bitrix24 REST.

Timeline

Basic integration (deals, contacts, tasks) with OAuth and pagination: 1-2 weeks. Adding webhooks, push notifications and offline buffer: plus 1 week. Cost calculated individually.