
Configuring Bitrix24 as a Source
In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Bitrix24 option from the list of connectors. Click Next and you’ll be prompted to add your access.1. Add account access
The connector supports two authentication modes:- OAuth (default): Install the Nekt app on your Bitrix24 instance using the install button, provide your Domain URL (e.g.
https://yourworkspace.bitrix24.com/), and sign in with Bitrix24 to authorize Nekt. - Webhook: Provide an Incoming webhook URL for your Bitrix24 portal. Check the Bitrix documentation for how to create an incoming webhook and copy its URL.
-
Authentication mode:
oauth(default) orwebhook. - Domain URL: The domain URL of your Bitrix24 workspace. Required in OAuth mode; in webhook mode the domain is read from the webhook URL.
- Incoming webhook URL: The Bitrix24 incoming webhook URL used for API calls. Required in webhook mode.
-
Extract deal contacts: (Default:
false) When enabled, performs an additional API call per deal to retrieve related contact IDs. Enable only if your deals have multiple clients and you need that list. -
Enable deal comments stream: (Default:
false) When enabled, thedeal_commentsstream becomes available. Selecting it triggers one extra API call per deal to fetch comments. Enable only if needed, as it increases extraction time. -
Enable deal products stream: (Default:
false) When enabled, thedeal_productsstream becomes available. Selecting it triggers one extra API call per deal to fetch products. Enable only if needed, as it increases extraction time. -
Enable quote products stream: (Default:
false) When enabled, thequote_productsstream becomes available. Selecting it triggers one extra API call per quote to fetch its products. Enable only if needed, as it increases extraction time. - Operating time threshold: (Default: 200) If Bitrix returns an “operating time” greater than this value (in seconds), the tap will pause for that duration before continuing. Use this to respect rate limits.
- Filter deal category IDs: (Optional) List of Bitrix deal category IDs (funnels). If set, only deals from these categories are extracted. Leave empty to sync all deals.
-
SPA Column Name Overrides: (Advanced, optional) Map specific Bitrix SPA field codes to exact column names, to control how case-colliding custom fields are separated. Example:
{"ufCrm10Fotoprincipal": "ufCrm10Fotoprincipal_2"}. Leave empty to use automatic collision resolution. -
Enable BI reports: (Default:
false) Enables the Bitrix24 BI Connector report streams (such as Open Channels session statistics). The BI Connector is a separate integration from the webhook and requires its own key. - BI connector key: Bitrix24 BI connector key, generated under CRM -> Analytics -> BI analytics -> Manage keys. Required when ‘Enable BI reports’ is on.
- BI reports start date: First day to pull BI report data from on the initial sync.
- BI reports window size (days): (Default: 30) Size in days of each BI Connector request window. Smaller windows reduce per-request row counts to stay under plan limits.
- BI reports lookback (days): (Default: 30) Number of days re-pulled before the saved bookmark on incremental BI report syncs, to capture updates to recently created sessions.
Scopes for data access
Scopes for data access
- CRM:
crm— contacts, companies, deals, deal categories, leads, activities, products, status list, SPA types (and optionally deal comments, deal products). - Users:
user,user_brief,user_basic— user list and profile data. - Company structure:
departments— departments. - Telephony:
telephony— calls (Voximplant statistics). - Open lines:
imopenlines— open line configurations.
2. Select streams
Choose which data streams you want to sync. Visibility depends on your webhook scopes and on the optional settings above (deal comments, deal products). You can select entire groups of streams or pick specific ones.Tip: The stream can be found more easily by typing its name.
If you don’t see a stream you were expecting to find, please check if your access key has the required scope. If that’s not the issue, then it’s probably because we still haven’t implemented it. Feel free to get in touch and request it!
3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data), and the type of sync.- Layer: Choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
- Folder: A folder can be created inside the selected layer to group all tables being created from this new data source.
- Table name: We suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
- Sync Type: You can choose between INCREMENTAL and FULL_TABLE.
- Incremental: every time the extraction happens, we’ll get only the new data — which is good if, for example, you want to keep every record ever fetched.
- Full table: every time the extraction happens, we’ll get the current state of the data — which is good if, for example, you don’t want to have deleted data in your catalog.
4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:- Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
- Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
5. Check your new source
You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.Troubleshooting
Streams and Fields
Available streams
The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description. Streams marked optional are only discovered when the corresponding setting is enabled.Fields by stream
Below you’ll find all available data streams from Bitrix24 and their main fields. CRM entity streams (contacts, companies, deals, leads, activities, product) have schemas built dynamically from the Bitrix API, so custom fields (e.g.UF_*) may vary per portal.
activities
activities
Stream for CRM activities (calls, meetings, tasks, etc.). Schema is built from the Bitrix API.Key fields:
activity_fields
activity_fields
Metadata stream for activity field definitions (types, labels, options).Key fields:
calls
calls
Stream for telephony (Voximplant) call statistics. Requires scope
telephony.Key fields:companies
companies
Stream for CRM companies. Schema is built from the Bitrix API.Key fields:
company_fields
company_fields
Metadata stream for company field definitions.Key fields:
contacts
contacts
Stream for CRM contacts. Schema is built from the Bitrix API.Key fields:
contact_fields
contact_fields
Metadata stream for contact field definitions.Key fields:
deal_categories
deal_categories
Stream for deal categories (pipelines/funnels). Schema is built from the Bitrix API.Key fields:
deal_comments
deal_comments
Stream for comments attached to deals. Available only when “Enable deal comments stream” is turned on. One API call per deal.Key fields:
deal_fields
deal_fields
Metadata stream for deal field definitions.Key fields:
deal_products
deal_products
Stream for products (line items) linked to deals. Available only when “Enable deal products stream” is turned on. One API call per deal.Key fields:
deals
deals
Stream for CRM deals. Schema is built from the Bitrix API. Optionally can include
CONTACT_IDS per deal when “Extract deal contacts” is enabled.Key fields:deal_stage_history
deal_stage_history
Stream for deal stage (pipeline step) change history.Key fields:
departments
departments
Stream for company structure (departments). Requires scope
departments.Key fields:lead_fields
lead_fields
Metadata stream for lead field definitions.Key fields:
leads
leads
Stream for CRM leads. Schema is built from the Bitrix API.Key fields:
lead_stage_history
lead_stage_history
Stream for lead stage change history.Key fields:
open_lines
open_lines
Stream for Open Lines (communication channels) configuration. Requires scope
imopenlines.Key fields:product
product
Stream for CRM product catalog. Schema is built from the Bitrix API.Key fields:
product_fields
product_fields
Metadata stream for product field definitions.Key fields:
quotes
quotes
Stream for CRM quotes. Schema is built from the Bitrix API. Supports incremental sync using the
DATE_MODIFY replication key.Key fields:quote_fields
quote_fields
Metadata stream for quote field definitions.Key fields:
quote_products
quote_products
Stream for products (line items) linked to quotes. Available only when “Enable quote products stream” is turned on. One API call per quote.Key fields:
spa_types
spa_types
Stream for SPA (Smart Process Automation) entity types. Used to discover dynamic SPA streams.Key fields:
spa_{entityTypeId} / spa_fields_{entityTypeId}
spa_{entityTypeId} / spa_fields_{entityTypeId}
Dynamic streams created per SPA entity type in your Bitrix portal (e.g.
spa_128, spa_fields_128). Data and field metadata for each SPA entity type; structure depends on your Bitrix configuration.status_list
status_list
Stream for CRM status list (e.g. deal/lead status options).Key fields:
users
users
Stream for Bitrix24 users. Requires scopes
user, user_brief, user_basic.Key fields:SPA Stage History
SPA Stage History
Stream containing the stage history records for Smart Process Automations (SPAs). Incremental sync is supported using
CREATED_TIME.Key fields:Data Model
The following diagram illustrates the relationships between the core data streams in Bitrix24. CRM entities relate as follows: Contacts and Companies are standalone; Deals and Leads can be linked to contacts and companies. Deals are organized by Deal Categories (funnels/pipelines). Activities can be attached to deals, contacts, and other entities. product is the catalog; deal_products links products to deals. Users and departments describe your organization; calls and open_lines are telephony and communication data. Field streams (*_fields) describe the schema of their entity (contact, company, deal, lead, activity, product, SPA).
BI Connector streams
Below you’ll find the specific data streams available when using the BI Connector in Bitrix24 (ensureEnable BI reports is turned on). The connector also fetches standard CRM and organizational streams via the outbound webhook (documented above).
Open Channels Session Stats (imopenlines_session_stats)
Open Channels Session Stats (imopenlines_session_stats)
Open Channels dialog statistics from the Bitrix24 BI Connector. It exposes one row per Open Channels session (dialog) with pre-computed SLA metrics: response times, dialog duration, timestamps, operator, channel and status.
Implementation Notes
- Optional streams:
deal_commentsanddeal_productsappear only when enabled in the source configuration and add one API call per deal;quote_productsappears only when enabled and adds one API call per quote. Use only if needed. - Deal filtering: Use “Filter deal category IDs” to sync only specific funnels and reduce volume.
- Rate limits: If Bitrix returns high “operating time” values, the tap pauses automatically; you can adjust “Operating time threshold” if needed.
- SPA streams:
spa_typesis synced first; then onespa_{id}and onespa_fields_{id}stream per SPA entity type in your portal. - Connection resilience: Schema discovery includes connection pooling and an automatic retry mechanism with exponential backoff (up to 5 attempts). This improves stability when dealing with temporary network issues or API timeouts during the initialization phase.
- SPA custom field collisions: Bitrix24 Smart Process Automations can return custom fields whose codes differ only by letter case (e.g.,
ufCrm10FotoPrincipalvsufCrm10Fotoprincipal). To avoid data collapsing into a single column, the connector preserves the original column names exactly as returned by Bitrix and automatically resolves collisions by appending a numeric suffix (e.g.,_2,_3) to the overlapping fields. If you need to enforce a specific mapping without changing your Bitrix24 setup, pin the names using the SPA Column Name Overrides setting.
BI Connector Replication & Data Quirks
When utilizing the BI Connector to extract reports likeimopenlines_session_stats, be aware of the following behaviors and quirks:
- Incremental Syncs on
DATE_CREATE: The BI dataset has noDATE_MODIFYcolumn, soDATE_CREATEis used as the replication key. - Mutable Sessions: A session created today might be answered or closed days/weeks later, which backfills its stats (e.g.
TIME_*,DATE_*). The primary key isID, and downstream merges should perform an upsert. Thebi_reports_lookback_daysconfiguration handles re-pulling recent sessions to capture late updates. - Timestamps: All timestamps are portal-local (e.g.
YYYY-MM-DD HH:MM:SSin the account’s configured timezone) and are landed as-is without timezone conversions. - String replication key: Because BI datasets expose naive, portal-local timestamp strings, the replication key is landed unchanged as a string type rather than a timestamp type. The connector safely parses the raw bookmark value internally to calculate the proper lookback windows without causing timestamp validation errors, ensuring reliable incremental syncs for BI reports.
- Inflated Response Times: Unanswered sessions will show constantly accruing
TIME_*metrics while a client waits. Filter on answered status states before computing SLA aggregates. - No Operator on Certain Channels: Sessions coming from Facebook or Instagram comments might register an
OPERATOR_IDof0with a null operator name.
Skills for agents
Download Bitrix24 skills file
Bitrix24 connector documentation as plain markdown, for use in AI agent contexts.