Bitrix24 Integration with Asterisk
Asterisk has been running as the primary corporate PBX at many companies for several years. When a business migrates to Bitrix24, the question arises: should you discard all telephony infrastructure and switch to Bitrix24's cloud telephony, or keep Asterisk and connect it to CRM? In most cases — keep it. Asterisk provides configuration flexibility that cloud PBX lacks, while the integration with Bitrix24 delivers everything needed from CRM: a pop-up contact card, call recording, and automatic lead creation.
Two architectural approaches
SIP trunk from Asterisk to Bitrix24. Asterisk registers as a SIP trunk in the Bitrix24 cloud PBX. Inbound and outbound calls pass through Asterisk, while the media stream and signaling go to Bitrix24. Call routing and IVR can remain in Asterisk or be moved to Bitrix24.
Advantage: all routing logic stays on Asterisk; Bitrix24 receives only CRM events. Disadvantage: the media stream passes through Bitrix24 servers — additional latency.
AGI/AMI integration without media stream transfer. Asterisk handles calls independently, while only events are sent to Bitrix24: call started, call ended, duration, result. AMI (Asterisk Manager Interface) or an AGI script is used.
This is the preferred option if Asterisk is already configured with the provider and call quality is satisfactory. Bitrix24 receives all CRM functionality without changing the telephony infrastructure.
AMI configuration: step-by-step scheme
AMI is Asterisk's TCP interface for management and monitoring. Via AMI, you can subscribe to call events and send commands.
1. Create an AMI user in /etc/asterisk/manager.conf:
[bitriks_agi]
secret = your_secret_password
read = call,cdr
write = originate
permit = 127.0.0.1/255.255.255.0
2. Deploy a handler — a small daemon (Node.js, PHP-daemon, or Python) that listens for AMI events:
-
Newchannel— new inbound call -
Hangup— call ended -
Bridge— connection established (operator answered)
3. On Newchannel event, call Bitrix24 REST:
POST /rest/telephony.externalcall.register
{
"USER_PHONE_INNER": "101",
"USER_ID": 5,
"PHONE_NUMBER": "+74951234567",
"CALL_START_DATE": "2024-01-15T10:30:00+03:00",
"CRM_CREATE": "Y",
"CRM_SOURCE": "CALL_TRACKER",
"TYPE": 2
}
4. Save CALL_ID from the Bitrix24 response — it will be needed to complete the call and attach the recording.
5. On Hangup event, call:
POST /rest/telephony.externalcall.finish
{
"CALL_ID": "saved_CALL_ID",
"USER_ID": 5,
"DURATION": 185,
"STATUS_CODE": "200",
"ADD_TO_CHAT": "Y"
}
Call recordings and transfer to Bitrix24
Asterisk writes call recordings to a directory (typically /var/spool/asterisk/monitor/). After the call ends, the recording file must be transferred to Bitrix24.
Via API:
POST /rest/telephony.externalCall.attachRecord
{
"CALL_ID": "CALL_ID",
"FILENAME": "record_2024_01_15_101.mp3",
"FILE_CONTENT": "<base64 encoded file content>"
}
For large recordings (calls longer than 5–10 minutes), base64 is inefficient. Alternative: upload via disk.file.uploadurl.prepare — obtain an upload URL and send the file directly.
Outbound calls from Bitrix24 via Asterisk
A manager clicks a number in CRM — Asterisk must place the call. Implemented via Bitrix24 REST API event OnExternalCallStart or via telephony.externalcall.originate. The handler receives the event and executes an originate command in Asterisk via AMI:
Action: Originate
Channel: SIP/101
Exten: +74951234567
Context: outbound
Priority: 1
CallerID: "Peter Ivanov" <+74955551234>
Case study: call center with 12 operators
A telecommunications company with its own Asterisk 18, 12 operators, queues, and IVR. The migration to Bitrix24 was driven by the need to maintain a client communication history — operators did not know whether a client had called before or what issue they had raised.
AMI integration was preferred because all routing (queues, IVR, transfers) was already configured in Asterisk and working without issues. Moving this to Bitrix24 was impractical.
A non-standard scenario: in an Asterisk queue, a call could be transferred between operators (first one did not answer — it goes to the next). It was necessary to correctly identify which Bitrix24 operator to assign the call to. Solved by tracking the AgentConnect event in AMI — this is the event that records which agent accepted the call from the queue.
AMI integration setup timeframe including recording transfer and outbound calls: 5–8 business days.
Common errors
Calls are duplicated in CRM — if Asterisk creates a new channel when transferring a call, the AMI handler registers it as a new call. Filtering by LinkedID in AMI events resolves the issue: this is the original call ID, which does not change during transfer.
Recording not attached — the recording file is not ready at the time of the Hangup event. Asterisk converts .wav to .mp3 asynchronously. Add a 5–10 second delay or monitor file appearance via inotify.