Client Change Event CallCard::EntityChanged

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::EntityChanged event occurs when the client bound to the call changes.

The event arrives in four cases:

  • the call card opened and pulled up CRM data
  • the card refreshed the client data
  • a CRM item was created or bound from the card — a lead, a contact, or a company
  • in call campaign mode, the operator moved on to the next client

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({
            "PHONE_NUMBER": "+19001234567",
            "CRM_ENTITY_TYPE": "CONTACT",
            "CRM_ENTITY_ID": 123
        });

Event Handler Parameters

Required parameters are marked with *

Parameter
type

Description

PHONE_NUMBER*
string

The client's phone number.

If the client has no phone number at all, the string unknown arrives

CRM_ENTITY_TYPE*
string

The type of the CRM object linked to the call

CRM_ENTITY_ID*
integer

The identifier of the CRM object linked to the call

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::EntityChanged

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::EntityChanged', function (eventData) {
                    console.log(eventData);
                });
            });
        });
        
// $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::EntityChanged', (eventData: { PHONE_NUMBER: string; CRM_ENTITY_TYPE: string; CRM_ENTITY_ID: number }) => {
          console.log(eventData.CRM_ENTITY_ID)
        })
        
<!-- 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::EntityChanged', (eventData) => {
              console.log(eventData)
            })
          })
        </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 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
Enable Auto-Close
Next
Before Close Card Event