Call Card CALL_CARD: Overview of Commands and Events

The CALL_CARD placement adds an application widget as a tab in the CRM call card. Through the JS interface, the application retrieves data of the current call, controls the auto-closing of the card, and reacts to a change of the client or of the call state.

Quick navigation: all commands and events

User documentation: Call Card

Getting Started with CALL_CARDGetting Started with CALL_CARD

1. Register the CALL_CARD placement with the placement.bind method — the widget appears as a tab in the call card. How the placement itself is arranged and which data the handler receives when it opens is described on the page Call Card Tab CALL_CARD
2. Make sure the widget is open in this exact card: the list of available commands and events is returned by BX24.placement.getInterface
3. Retrieve the data of the current call with the getStatus command
4. Subscribe to changes in the card with the BX24.placement.bindEvent method

A minimal working cycle: the application reads the call data and tracks the change of its state.

BX24.ready(function () {
            BX24.init(function () {
                BX24.placement.call('getStatus', {}, function (status) {
                    console.log(status.CALL_ID, status.PHONE_NUMBER);
                });
        
                BX24.placement.bindEvent('CallCard::CallStateChanged', function (callState) {
                    console.log(callState);
                });
            });
        });
        

How a Placement Command Call WorksHow a Placement Command Call Works

A command is invoked by name: pass the command name as the first argument of BX24.placement.call, the parameters object as the second, and the callback function as the third.

None of the CALL_CARD commands accepts parameters — pass an empty object {} as the second argument.

The getStatus command returns the data of the current call, while the auto-close commands return an empty array. They have no error codes of their own.

If the widget is open outside the call card, the placement interface ignores the unknown command: the callback function is not invoked at all.

Events arrive in the callback function passed to BX24.placement.bindEvent. The handler receives client data, the call state with additional parameters, or a call without data if the card is closing.

How Auto-Closing of the Card WorksHow Auto-Closing of the Card Works

By default, the card disappears right after the conversation, and the widget closes with it. To give the user time to fill in the application form, auto-closing is blocked.

1. The conversation ends, and Bitrix24 tries to close the card
2. If auto-closing is blocked by the disableAutoClose command, the CallCard::BeforeClose event arrives and the card stays on screen for another 65 seconds. Each repeated call of disableAutoClose extends the countdown
3. When the application has finished its work, it calls enableAutoClose. The block is lifted, and the card closes if the conversation has already ended

BX24.ready(function () {
            BX24.init(function () {
                // the user started filling in the form — do not let the card close
                BX24.placement.call('disableAutoClose', {}, function () {
                    console.log('auto-closing is blocked');
                });
        
                BX24.placement.bindEvent('CallCard::BeforeClose', function () {
                    // the card is about to be closed: save the form data
                    saveFormData().then(function () {
                        BX24.placement.call('enableAutoClose', {}, function () {
                            console.log('auto-closing is restored');
                        });
                    });
                });
            });
        });
        

How to Choose a Command or an EventHow to Choose a Command or an Event

Overview of Commands and EventsOverview of Commands and Events

Scope: placement — registration of the placement, telephony — access to the call card placement

Who can execute the commands: any user

Typical ErrorsTypical Errors

Continue LearningContinue Learning

• Call Card Tab CALL_CARD
• Call the Registered Interface Command BX24.placement.call
• Set Up an Event Handler for the Interface BX24.placement.bindEvent
• Manage the Call Card of a WebRTC Client: Overview of Commands and Events
• Interaction with UI: Overview of Methods