Call Card
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— registration of the call that raises the cardWho can execute the commands: the employee to whom Bitrix24 displays the card, provided they have access to the application
The call card is the window in which the operator sees a call and manages it: answers it, ends the conversation, puts it on hold, or transfers it to a colleague. A telephony application with its own WebRTC client changes the title, the status text, and the set of buttons of the card. The application learns about button clicks from events and performs the call action itself, for example, ends the call in its own client. Bitrix24 also handles the Close button on its own: the button sends an event and closes the card.
Only the card of an external call can be managed. The application registers the call with the telephony.externalCall.register method, and Bitrix24 displays the card to the operator — the employee specified in the USER_ID or USER_PHONE_INNER parameter of that method. Whether the card is displayed depends on the SHOW parameter: it defaults to 1, and with 0 the card appears only after the telephony.externalCall.show method is called. Commands and events go through the background handler in the PAGE_BACKGROUND_WORKER placement.
The card management commands start working after the BackgroundCallCard::initialized event, which arrives when the card is created. Before this event, after the card is closed, and during a regular Bitrix24 call, they return the Call card is undefined error. The CallCardGetListUiStates command works even without a card.
For instructions on registering a handler, see WebRTC Embedding Scenario. All commands and events are listed in the section overview Manage the Call Card of a WebRTC Client: Overview of Commands and Events.
Card Structure
To change the title at the top of the card, call the CallCardSetCardTitle command and pass an object with the title property.
BX24.placement.call('CallCardSetCardTitle', { title: 'Card Title' }, (result) => {
console.log(result); // [] — the title is changed
});
To change the status text below the name of the other party, call the CallCardSetStatusText command and pass an object with the statusText property.
BX24.placement.call('CallCardSetStatusText', { statusText: 'Status Text' }, (result) => {
console.log(result); // [] — the text is changed
});
The buttons at the bottom of the card depend on the interface state. The CallCardGetListUiStates command returns 12 states to which the application can switch the card: the callback function receives an array of their codes.
BX24.placement.call('CallCardGetListUiStates', {}, (data) => {
console.log(data);
});
The transition to another state of the card is performed by the CallCardSetUiState command: pass it an object with the uiState property.
BX24.placement.call('CallCardSetUiState', { uiState: 'connected' }, (result) => {
console.log(result); // [] — the state is changed
});
To find out which buttons the operator clicks, subscribe to events with the BX24.placement.bindEvent method. The table below shows which event each button sends, and the events are described in the section Overview of Events for Working with the Call Card of a WebRTC Client.
Card States
Right after it appears, the card is in an internal state: it has only the Close button at the bottom. This state is not listed in the table below or in the response of the CallCardGetListUiStates command. To show the operator the required buttons, switch the card to one of the states with the CallCardSetUiState command.
|
State |
When Used |
Buttons and Events |
|
incoming |
For accepting incoming calls |
|
|
transferIncoming |
For accepting a redirected incoming call |
|
|
outgoing |
For displaying the outgoing call card |
|
|
connectingIncoming |
For displaying the card while connecting to an incoming call |
|
|
connectingOutgoing |
For displaying the card while connecting to an outgoing call |
|
|
connected |
For displaying after connecting to the call |
|
|
transferring |
For confirming the transfer of the call to another operator |
|
|
transferFailed |
If the call transfer failed |
|
|
transferConnected |
If the transfer was successful and you need to exit the call card |
|
|
error |
If a call error occurred |
|
|
moneyError |
If the account runs out of money and you need to inform the Bitrix24 administrator |
|
|
redial |
If the subscriber is busy and the operator needs to call this number again without closing the call card |
|
The call quality indicator in the connected state does not accept clicks and does not send events.
Call Timer
When the card switches to the connected state, the call timer starts automatically. To prevent it from starting, pass the disableAutoStartTimer: true property along with uiState: 'connected'.
In the call transfer states — transferring, transferFailed, and transferConnected — the timer keeps running. All other states except connected stop the timer. You can stop or restart the timer with the CallCardStopTimer and CallCardStartTimer commands.