Bitrix24 Integration

AICA integrates with Bitrix24 CRM as an embedded application, providing automatic call ingestion, AI-powered analysis, and results delivered directly to CRM entities.

Overview

• Automatic call ingestion via Bitrix24 webhooks
• Analysis results pushed back to CRM contact and deal fields
• Embedded analytics dashboard inside contact and deal cards
• Single sign-on through the Bitrix24 iframe session

Installation

1. Install the app. Open the Bitrix24 Marketplace or use the direct installation link provided by your AICA administrator.
2. Authorize. Grant the requested OAuth 2.0 permissions. AICA requires access to CRM activities, contacts, and deals.
3. Automatic setup. On first authorization, AICA automatically creates the necessary custom CRM fields (quality score, summary, compliance status, etc.).
4. Configure project mapping. In AICA Settings, map your Bitrix24 telephony lines to AICA projects to control which analysis profile is applied to each call source.

How Call Ingestion Works

Bitrix24                         AICA
   │                              │
   │  ONCRMACTIVITYADD webhook    │
   │ ───────────────────────────> │
   │                              │  1. Validate webhook signature
   │                              │  2. Download audio from B24
   │                              │  3. Start processing pipeline
   │                              │     (ASR → Analysis → QA)
   │                              │
   │  REST API: update CRM fields │
   │ <─────────────────────────── │  4. Push results back to CRM
   │                              │

1. When a call activity is completed in Bitrix24, the CRM fires an ONCRMACTIVITYADD webhook.
2. AICA validates the webhook signature (HMAC-SHA256) and downloads the audio recording via the Bitrix24 REST API.
3. The audio enters the standard AICA pipeline: speech-to-text, PII redaction, AI analysis, and quality scoring.
4. Once processing completes, AICA writes the results back to the associated CRM contact or deal as custom fields.

CRM Field Mapping

Configure which analysis fields are written back to Bitrix24 in Project Settings > Delivery > Bitrix24 Fields.

AICA Field	Default CRM Field Name	Description
qualityScore	UF_AICA_QUALITY	Overall quality score (0-100)
summary	UF_AICA_SUMMARY	AI-generated call summary
improvements	UF_AICA_IMPROVEMENTS	Suggested improvements
complianceStatus	UF_AICA_COMPLIANCE	Compliance check result

You can rename the CRM fields and choose which ones to enable per project. Only enabled fields are written on each analysis completion.

Embedded Dashboard

AICA provides an embedded widget that appears inside Bitrix24 contact and deal detail pages:

• Recent calls for the selected contact with scores and status indicators.
• Call details with transcript, analysis breakdown, and playback controls.
• Score trends showing quality over time for that contact or deal.

No separate login is required. The widget authenticates automatically through the Bitrix24 iframe session (see Embedded Authentication).

Troubleshooting

Calls not appearing in AICA

1. Verify the webhook URL is correctly configured in Bitrix24 under Developer resources > Webhooks.
2. Check that the webhook includes the crm scope.
3. Confirm the telephony line is mapped to an AICA project in Settings.
4. Review delivery logs in AICA Settings > Delivery Status for failed webhook receipts.

OAuth token expired

Bitrix24 OAuth tokens expire periodically. If AICA cannot push results back to CRM:

1. Open the AICA app in Bitrix24 to trigger a token refresh.
2. If that does not resolve the issue, reinstall the app from the Marketplace.

CRM fields not updating

1. Verify field mapping is configured in Project Settings.
2. Check that the target fields exist in the CRM entity (they are created automatically on install, but may have been deleted manually).
3. Review the delivery log for specific error messages (e.g., insufficient permissions).

Webhook signature validation failures

Ensure the webhook secret in AICA matches the one configured in Bitrix24. Rotate the secret from AICA Settings > Integrations > Bitrix24 if needed.