Bitrix24 two-way sync: setup, field mapping and all settings

Bitrix24 two-way sync matters when requests come into the account's CRM while managers run deals in Bitrix24. Without it, a lead after a bot call or a website request is copied by hand. A stage change in Bitrix24 never reaches the account, and automated funnels work with outdated data.

A Bitrix24 two-way integration is an exchange of leads and deals between two CRMs through Bitrix24 webhooks. A lead reaches the chosen step, and a deal appears or updates in Bitrix24. A deal moves to the chosen stage, and the lead's step changes in the account. Along with the step and stage, fields, the responsible person, the amount, the source, the dialog and the call recording are transferred — according to the mapping you set up. Everything is configured on the /land/bitrix/bitrix.php page: below we go through each of its blocks, fields and checkboxes. Watch the two-minute video, and the step-by-step setup is below.

Why businesses need Bitrix24 two-way sync

• Sales in Bitrix24, first contact by bots. A lead that the voice bot brought to the “Meeting booked” step lands as a deal on the right stage on its own, with the phone number, fields and the call recording.
• Call center in the account, sales team in Bitrix24. A manager moves the deal, and the lead's step in the account follows, so call-outs and automated funnels use the current status.
• The bot calls deals from Bitrix24. A manager moves deals to the call-out stage, the bot calls by itself, and only qualified clients come back to the sales team, with the call recording.
• One responsible person in both systems. Employee pairs are matched once, and the deal goes to the same manager as the lead.
• The head of sales sees one picture. There is no need to merge exports from two CRMs to see how many clients reached payment.

How the Bitrix24 two-way integration works

• From the account to Bitrix24. A lead reaches a step from block 4. The integration first looks for the card by its link: if this lead was sent before, the integration remembers its card for a year after the last exchange. No link — it searches by phone, through the contact. If found, it updates the most recent card; if not, it creates a new one on the chosen stage.
• From Bitrix24 to the account. Bitrix24 reports new and changed leads and deals. If the card is on a stage from block 3, the integration finds the account's lead by link or by phone and sets the step, fields and owner. If there is no lead, it creates a new one.
• Bitrix24 leads and deals. The pipeline list has a “Bitrix leads” item — with it, the exchange works with Bitrix24 leads and their statuses. The other items in the list are deal pipelines.
• No loop. Each step and each stage can be chosen only once across both blocks. Besides, the stage is not rewritten if the card is already on it, and the step is not rewritten if the lead is already on it. So a change that came from Bitrix24 is not sent back.

The voice bot does not write to Bitrix24 by itself. It saves call results to the lead card through the “Writing to CRM” section, as described in the article ai voice bot crm integration. When the bot moves the lead to a step from block 4, the data goes to Bitrix24.

How to set up Bitrix24 two-way sync

1. 1
   Create an inbound webhook in Bitrix24

   In the Bitrix24 webhooks section (“Applications” → “Developer resources” → “Other” → “Inbound webhook”, or “Applications” → “Webhooks” in some versions), add an inbound webhook with the crm, user and telephony permissions. The telephony permission is needed for the call with its recording to reach the card. Copy the webhook address, which looks like https://…bitrix24.ru/rest/1/…/. The integration creates and moves deals on behalf of the employee who created the webhook.
2. 2
   Create an outbound webhook

   Choose the ONCRMLEADADD, ONCRMLEADUPDATE, ONCRMDEALADD and ONCRMDEALUPDATE events. Other events, such as recurring deal events, are not needed: the integration accepts only these four. Take the handler address from the settings page: the “Paste this link into the outbound webhook in Bitrix” link copies it, and “Link copied” appears. Save the webhook and only then copy its application token.
3. 3
   Open the settings page

   /land/bitrix/bitrix.php on your account's domain.
4. 4
   Fill in the “1. Bitrix24 authorization” block

   Paste the inbound webhook address into “Enter the Bitrix24 inbound webhook” and the token into “Enter the application token of the Bitrix24 outbound webhook”. “Bitrix login” and “Bitrix password” are optional. Click “Sign in to Bitrix” and wait for “All data loaded successfully.”.
5. 5
   Sign in to the account in block 2

   Enter the project number, the account login (email) and password, and click the sign-in button. Funnel steps, fields, employees and saved settings load, and the first two blocks hide.
6. 6
   Set up block 3

   What comes from Bitrix24 to the account: a Bitrix24 pipeline and status → an account funnel step.
7. 7
   Set up block 4

   What goes from the account to Bitrix24: an account funnel step → a Bitrix24 pipeline and status, plus the duplicate and contact checkboxes.
8. 8
   Map the fields

   In the “Field mapping for pipeline…” tables under each block: field pairs, list values and employees.
9. 9
   Click “Save”

   At the bottom of the page. “Saving integration settings...” appears, then “Integration settings saved.” and a message that the webhook was set up successfully.

Block 3: what comes from Bitrix24 to the account

A row of the block is three lists: “Choose a Bitrix pipeline”, “Choose a Bitrix pipeline status” and the account funnel step. When a Bitrix24 card reaches this status, the lead in the account moves to the chosen step. The “Add pipeline” button adds the next row, and “Delete” removes an extra one. If several rules match one stage, the first one applies.

Repeat lead. The “Create a repeat lead” checkbox and the “Funnel step … for the repeat lead” list. Without the checkbox, a new request from Bitrix24 goes into the client's existing lead. With it, the integration creates a new lead of the same contact on the chosen step, so repeat requests are visible in the funnel. A repeat lead is created once per Bitrix24 card: further changes to that card go into the same lead. Fields follow the mapping of the original step. Without a chosen step the setting does not turn on. It is saved with its own “Save” button right in this block.

Block 4: what goes from the account to Bitrix24

A row of the block is the account funnel step, “Choose a Bitrix pipeline” and “Choose a Bitrix pipeline status”. A lead reaches this step, and the card in Bitrix24 is created or moved to this status. One rule applies to each step. Under the status there are checkboxes for this row:

• “Create 1 duplicate”. The number is clickable, and the “Enter the number of duplicates:” window sets it. While the client has that many cards or fewer, the integration creates a new one instead of updating the old one. All deals count, including closed ones. No duplicate is created for a card found by link.
• “Create contact”. On by default: the integration finds the contact by phone and updates the name and email, or creates a new contact. Without the checkbox, the contact is not created or linked, and the email is added to the card's name and comment.
• “Search duplicates only in this stage”. Off by default: the card is searched in the whole pipeline, including closed deals. With the checkbox, only cards on the chosen stage count.
• “Sync both ways”. On saving, it adds the reverse rule: a card reaches this stage in Bitrix24, and the lead moves to this step. A separate row in block 3 is not needed. It works if the step has a single row.

Example: the bot calls deals from Bitrix24

A common setup: a manager hands a deal to the voice bot for a call right from Bitrix24, and the call result comes back to the deal.

• Block 3. The “For the bot to call” stage → the step the voice bot calls from: this step is chosen in its “Launch conditions”. The manager moves the deal, the lead lands on the step, and the bot calls the client.
• Block 4. The “Interest confirmed” step → the “Qualified lead from the bot” stage. The bot sets the step itself based on the call result, and the deal moves to this stage with the call recording and comments.
• Answering machines. Match the “Answering machine” step, where the bot moves such calls, with a separate stage. This way answering machines don't mix with qualified leads.

Give steps and stages similar names, so the link is clear in both CRMs.

How to map fields between Bitrix24 and the account

When a pipeline is chosen in a row, a “Field mapping for pipeline … from Bitrix24 to …” table (block 3) or a “Field mapping for pipeline … to Bitrix24” table (block 4) appears under the block. The mapping is tied to the Bitrix24 pipeline and to the direction: each pipeline and “Bitrix leads” has its own, and the same pipeline in blocks 3 and 4 means two separate tables.

1. In “Bitrix field” (block 3) or in the account field (block 4), choose the field the pair starts with.
2. The second list shows only fields of a matching type. Under each field you see “Field type:”, and lists also show “List of values:”.
3. For lists and yes/no fields, fill in “Value mapping:” — for each value on one side, choose a value on the other. One value cannot be chosen twice.
4. “Add field” adds the next pair, and “Delete” removes an extra one. A half-filled row blocks saving.

The Bitrix24 field list contains only custom fields (their code starts with UF_CRM_) and special items. The standard name, stage, phone, email and contact cannot be mapped: the integration sends the phone, first name, last name and email by itself — to the contact, and for a Bitrix24 lead also to the card. Deal fields are shown according to the card settings of this pipeline in Bitrix24. On the account side, fields of the text, list, number and date types are available, including funnel step dates and the birthday.

Which field types can be mapped

Fields of the “CRM link”, “Employee” and “File” types are not in the lists: the integration does not send them in either direction. An empty value is not sent either — the Bitrix24 field is not cleared.

The “Stage date” is the date and time the client named for a callback: the voice bot writes it after the conversation. Map it to a “Date and time” field in Bitrix24, and the manager will see in the deal when to call back. In block 3 it works the other way too: the date from Bitrix24 comes into the “Stage date”, and a bot that calls by it will call back at the new time.

Special mapping items: employees, amount, source, comments

• “Bitrix employees” and account employees. Choose this item, and employee lists with an “Add employee” button appear on each side. Make pairs of managers. From the account, the lead owner becomes the responsible person in Bitrix24; no pair — the portal sets the responsible person itself. From Bitrix24, the responsible person becomes the lead owner; no pair — the owner does not change.
• dealDefaultMoney. The standard “Amount” of a Bitrix24 deal. Map it to a number field of the account: from the account the amount goes to the deal in the portal's base currency, with a comma replaced by a dot, and from Bitrix24 it comes into this field.
• “Source” → “Bitrix source”. Block 4 only. Sends the card's source, its description and UTM tags: utm_source, utm_campaign and utm_term, the website domain into utm_content and the capture type into utm_medium.
• “Comments” → “Bitrix comments”. The item is in the block 4 list, but sending the dialog is controlled by the “Send … comments to the card” checkbox and the “Bitrix field for comments” below — see the next sections.

From Bitrix24, the lead in the account gets its name from the card's title, or from the contact's name if there is no title. The phone is taken from the card or the contact, and if there is none, it is searched for in the title. A contact in the account is always created.

Bitrix24 deal name: template and placeholders

“Deal name in Bitrix” is one setting for the whole project, and it applies to all block 4 steps. Empty — the default name: for a deal, the system name and the phone number; for a Bitrix24 lead, the first name, last name and phone. The “+ insert a placeholder…” list inserts placeholders at the cursor.

For example, the template “{fio} — {phone}, request {date}” gives “Anna Smirnova — 79001234567, request 08.11.2026”. Unknown Latin placeholders are removed, and the name is limited to 250 characters. A new card always gets the template name, while an existing deal is renamed only if a template is set.

Call recording, comments and calls

• “Send the call recording link to the card”. On by default. The link goes into the UF_CRM_CALL_RECORD_LEAD or UF_CRM_CALL_RECORD_DEAL field and as a separate comment in the timeline: with the field you open the recording in one click, filter deals and build reports. The call with its recording always reaches the card timeline, both for new and existing cards. Turn the checkbox off only if the field gets in the way: it protects against a duplicate recording when the portal does not let the card be read.
• “Send … comments to the card”. On by default: the dialog from the account reaches the Bitrix24 card. Clear the checkbox, and the dialog is written neither to the field nor to the timeline.
• “Bitrix field for comments”. “Note” by default. The list has only text fields. The dialog is appended to the field value, and text that is already in the card is not written again.
• “Who to log calls from”. The employee the call is logged under in the card. Not chosen — the call is logged under the portal administrator.
• “Author of actions in Bitrix24”. It only shows on whose behalf deals are created and moved. The only way to change the author is to recreate the inbound webhook on behalf of the right employee.

Protected stages, bot stop and field sync

• “Protected stages: where the integration is allowed to work”. Mark the stages the integration works with. With the others it does nothing in either direction: it does not create cards on them, does not move cards there, does not touch a card that sits there and does not accept events for it. Nothing marked — it works on all stages; a pipeline with no marks is allowed entirely. The buttons are “Save scope” and “Remove all restrictions”.
• “Stop the AI bot by a Bitrix field”. Create a field of the “List” type in the Bitrix24 lead or deal card (for example, “Stop bot” with the values “Yes” and “No”) or of the “Yes/No” type. On the page, choose “Where to look” (Lead or Deal), “Trigger field” and the values, then “Save trigger”. When this value is set in the card, the AI bot stops writing to the client. It fires once per card linked to a lead. To bring the bot back, click “Start bot” in the dialog card; to turn the feature off, click “Turn off”.
• “Sync field changes without a step change”. Normally data goes to Bitrix24 only when a lead reaches a step from block 4. With the “Turn on field sync without a step change” checkbox, field edits and call recordings also arrive from other steps: “On all steps without a rule” or “Only on marked steps”. The stage does not change and no new card is created — only an already linked card is updated. The button is “Save sync”.

Required fields and several projects on one portal

If the portal refuses to create a deal because of a required field, the page shows “Bitrix24 is not creating deals: required fields are empty” with a list of fields. Map such a field to an account field in block 4 or make it optional in Bitrix24. A required system field cannot be mapped — you can only make it optional in the card settings. Until the field is filled, leads stay in the queue and sending is retried.

If several projects are connected to one portal, the page says “Another … works on this Bitrix portal” and shows their settings. Each project has its own settings, and they are not carried over. If the rules of two projects start from the same Bitrix24 stage, only the first project gets the lead — use different stages.

How to save the settings

The “Save” button at the bottom appears when there is at least one complete row in block 3 and in block 4: there is no one-way setup. A half-filled row or field pair also blocks saving. The repeat lead, protected stages, bot stop trigger and field sync are saved immediately with their own buttons — the general “Save” does not write them.

After signing in again in block 1 (the page hints call it “Check connection”), pipelines, fields and employees reload, but nothing is written: “Check passed, but the settings are NOT saved yet.” and a “Save now” button appear at the bottom. If new fields or pipelines were added in Bitrix24, sign out with “Sign out” and sign in again — the lists will refresh.

What is sent in each direction

When the data appears in Bitrix24 and in the account

From the account, a lead is sent no earlier than 15 seconds after its last change: several edits of one client in a row go out as one update. If Bitrix24 does not respond, sending is retried on the next runs, and creating a deal gets up to 5 attempts. A task with no progress for more than a day is dropped and goes to the rejected log. A project's queue holds up to 50 leads at a time.

From Bitrix24, events arrive right away, and identical events within 3 seconds are merged. One webhook handles up to 120 events per minute — extra ones are not lost but checked in a batch once a minute. On an error, sending is retried up to 10 times every 2 minutes, and when the portal is overloaded, every 5 minutes.

Why a Bitrix24 deal is only partly filled

1. The field is standard: the integration fills the name, stage, phone and email by itself, and does not send other standard fields except the amount (dealDefaultMoney).
2. The field is not in this pipeline's card in Bitrix24, so it is not in the list either. Added a field — sign out and sign in on the page again.
3. The field type does not match — see the type table above. “CRM link”, “Employee” and “File” are not sent.
4. A list or yes/no field has no “Value mapping:” filled in.
5. The value is empty or the date is not in the dd.mm.yyyy or dd.mm.yyyy hh:mm form.
6. The mapping was made for a different pipeline: each Bitrix24 pipeline has its own.
7. “Create contact” is off — then the deal has no client name, and the email goes into the name and comment.
8. The card is on a protected stage or the rule leads to one.
9. The portal requires a field — see the warning on the page.
10. The lead has no phone or the project queue already holds 50 leads.

The 502 error and “File not found” during setup

“Error: HTTP 502” while loading pipelines or fields, “Error while checking…: HTTP 502” and “Error saving integration settings: Error: HTTP 502” mean that the server did not wait for a response. This happens on large portals with many pipelines and fields: on saving, all fields are loaded again. Wait a minute and repeat the action.

If after saving you see “Integration settings saved. The external service returned HTTP code 404” or 502, and the response says “File not found.” or shows an error page, the settings are saved but the webhook in the account is not set. Click “Save” again and wait for the message that the webhook is set.

An old address like …/rest/bitrix/webhook?id=… belongs to the former integration through robots and business processes. It does not work for the outbound webhook — take the link only from the settings page.

Permission errors: ACCESS_DENIED, NO_AUTH_FOUND, OVERLOAD_LIMIT

Permission errors show up after you sign in in block 2: the “Error writing webhooks” window opens with “Webhook permission errors found” items.

• insufficient_scope — the webhook lacks a permission. Add crm, user or telephony to the inbound webhook in Bitrix24 and save it.
• ACCESS_DENIED — “REST API is blocked or unavailable on your Bitrix24 plan”. Check that your Bitrix24 plan supports the REST API.
• NO_AUTH_FOUND — the webhook token is wrong or expired. Recreate the webhook in Bitrix24 and paste the new address into block 1.
• OVERLOAD_LIMIT — the Bitrix24 REST API is temporarily blocked because of overload. Bitrix24 support can lift the block.

How to check and turn off Bitrix24 two-way sync

To check: move a test lead with a phone number to a step from block 4 and wait 15 seconds — a card appears in Bitrix24 on the chosen stage, with the template name and mapped fields. Then move the deal to a stage from block 3 and check the lead's step and fields in the account.

There is no separate off button. To stop sending to Bitrix24, delete the integration webhook in the crm webhook section — “Webhooks on lead change”. To stop the reverse direction, delete the outbound webhook in Bitrix24. The inbound webhook turns off the exchange in both directions. To limit the exchange to some stages, mark them in “Protected stages”.

Read also: Bitrix24 integration, CRM webhook, AI voice bot CRM integration, Duplicate leads in CRM