Call Status Change Event CallCard::CallStateChanged

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

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

Who can subscribe: any user

The CallCard::CallStateChanged event occurs when the state of the current call changes.

The event operates within the application context in the CALL_CARD placement. This is a JS interface event, not a REST event: you cannot subscribe to it with a request to /rest/.

What the Handler Receives

Data is passed to the callback BX24.placement.bindEvent

callback(
            "idle",
            {
                "failedCode": "486"
            }
        );

Event Handler Parameters

Required parameters are marked with *

Parameter
type

Description

callState*
string

The current state of the call.

Possible values:

  • idle — no connection
  • connecting — establishing connection
  • connected — connection established

additionalParams
object

Additional data (detailed description).

The argument always arrives: if there is no additional data, it is an empty object. The asterisk marks the required subscription parameters, not the handler arguments

additionalParams Parameter

Parameter
type

Description

failedCode
string

The call termination code. It is passed only on an unsuccessful termination, when callState = idle.

The value is a SIP protocol code. For example, 486 — the subscriber is busy, 480 — the subscriber is unavailable

Event Subscription Parameters

The handler is registered from the widget with the BX24.placement.bindEvent method.

Required parameters are marked with *

Name
type

Description

event*
string

The name of the interface event.

For this event — CallCard::CallStateChanged

callback*
callable

The function Bitrix24 invokes when the event occurs. The handler arguments are described above

Code Examples

How to Use Examples in Documentation

BX24.ready(function () {
            BX24.init(function () {
                BX24.placement.bindEvent('CallCard::CallStateChanged', function (callState, additionalParams) {
                    console.log(callState);
                });
            });
        });
        
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide)
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        await $b24.placement.bindEvent('CallCard::CallStateChanged', (callState: string, additionalParams: { failedCode?: string }) => {
          console.log(callState, additionalParams.failedCode)
        })
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          document.addEventListener('DOMContentLoaded', async () => {
            const $b24 = await B24Js.initializeB24Frame()
        
            await $b24.placement.bindEvent('CallCard::CallStateChanged', (callState, additionalParams) => {
              console.log(callState)
            })
          })
        </script>

Errors

Check the following conditions.

  • The widget is open in the CALL_CARD placement. In other placements, the CallCard::* events are not registered, and the subscription silently fails
  • The call state has actually changed. Setting the same callState value again does not trigger the event
  • The event name is passed without typos and with the correct capitalization. The list of events available in the current placement is returned by BX24.placement.getInterface

Continue Learning

Previous
Before Close Card Event
Next
Overview of Commands and Events