Overview of Events for Working with the Call Card of a WebRTC Client
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.
The BackgroundCallCard::* events let an application react to the operator's actions in the call card and to changes of the interface state without additional polling.
These are events of the placement JS interface, not REST events. They have no server handler: the application subscribes to them in the browser with the BX24.placement.bindEvent method. They cannot be registered with the event.bind method, and the REST method placement.bindEvent does not exist.
Quick navigation: all events
How to Subscribe to Events
- Register the
PAGE_BACKGROUND_WORKERplacement with the placement.bind method — the procedure is described in the section overview Manage the Call Card of a WebRTC Client: Overview of Commands and Events - In the widget code, subscribe to the events you need with the BX24.placement.bindEvent method
- Raise the call card with the telephony.externalCall.register method. Events arrive only for an external call made by the application: during a regular Bitrix24 call, the card looks the same, but none of the
BackgroundCallCard::*events fire - Wait for the BackgroundCallCard::initialized event, and only after it manage the card with BX24.placement.call commands
BX24.ready(function () {
BX24.init(function () {
BX24.placement.bindEvent('BackgroundCallCard::initialized', function (eventData) {
console.log(eventData.CALL_ID);
});
BX24.placement.bindEvent('BackgroundCallCard::muteButtonClick', function (eventData) {
// eventData = true if the operator muted the microphone
});
});
});
You need to subscribe to each event separately: there is no subscription to all events at once.
An interface event cannot be unsubscribed from, and calling BX24.placement.bindEvent again with the same name adds a second handler, so the application handles the event twice. Subscribe once per widget load.
How to Choose an Event
|
Scenario |
What to use |
What arrives in the handler |
|
The application gained access to the created call card |
The initial call data and the CRM bindings |
|
|
The operator clicks the call control buttons |
BackgroundCallCard::muteButtonClick, BackgroundCallCard::holdButtonClick, BackgroundCallCard::hangupButtonClick, BackgroundCallCard::answerButtonClick |
The data of the specific action in the interface |
|
The operator works with the call transfer |
BackgroundCallCard::transferButtonClick, BackgroundCallCard::cancelTransferButtonClick, BackgroundCallCard::completeTransferButtonClick |
The data of the transfer scenario |
|
The card loaded the client data from the CRM, the client was identified, or the current client changed in a call campaign |
The client's number and the current CRM binding |
|
|
You need additional actions from the card interface, for example to save a comment, rate the call quality, or enter a digit on the keypad |
BackgroundCallCard::addCommentButtonClick, BackgroundCallCard::dialpadButtonClick, BackgroundCallCard::qualityMeterClick, BackgroundCallCard::notifyAdminButtonClick, BackgroundCallCard::nextButtonClick, BackgroundCallCard::skipButtonClick, BackgroundCallCard::makeCallButtonClick, BackgroundCallCard::closeButtonClick |
The value selected by the user or the parameters of the action |
Which buttons the operator sees in each state of the card and which event they trigger is shown on the page Call Card.
Overview of Events
Scope:
placement— registration of the placement,telephony— registration of the call that raises the cardWho can subscribe: any user
|
Event |
Triggered |
Data in the handler |
|
After the call card is created |
An object with the call data |
|
|
When a comment is saved in the call card |
A string with the comment text |
|
|
When the mute button is clicked |
|
|
|
When the hold call button is clicked |
|
|
|
When the close call card button is clicked |
No data |
|
|
When the current operator selects the operator to transfer the call to |
An object with the number and the target of the transfer |
|
|
When the "return to call" button is clicked |
No data |
|
|
When the "redirect" button is clicked |
No data |
|
|
When the "end" button is clicked |
No data |
|
|
When the "next" button is clicked |
No data |
|
|
When the "skip" button is clicked |
No data |
|
|
When the "answer" button is clicked |
No data |
|
|
When the CRM object linked to the call is loaded or changed |
An object with the number and the CRM binding |
|
|
When the "call" or "callback" button is clicked |
No data |
|
|
When the call quality is rated |
A string with a rating from 1 to 5 |
|
|
When one of the numeric buttons of the phone is pressed |
A string with the pressed key |
|
|
When the "notify administrator" button is clicked |
No data |
Typical Errors
|
Problem |
Cause and what to do |
|
The handler is never invoked |
The widget is open outside the |
|
The widget is in the right placement, but events do not arrive |
The call is not an external one. Events are emitted only for a card raised with the telephony.externalCall.register method; for calls made by Bitrix24 itself, the interface stays silent |
|
The handler is not invoked for one event only |
The event name is misspelled or uses different capitalization. The list of events of the current placement is returned by BX24.placement.getInterface |
|
Events arrive, but the card management commands return an error |
The commands were invoked before the BackgroundCallCard::initialized event, when there was no card yet |
|
The application waits for a confirmation that the event was handled |
The events are one-way: a handler cannot return a value to Bitrix24, and the application reacts with a separate command call or REST method call |
|
The application changed the card with a command and waits for a corresponding event |
The |
|
One handler runs twice |
The subscription was made more than once. There is no unsubscribing from interface events, so subscribe once per widget load |