Diagram of call processing by Itgrix integration module
"Entity" in connector logic is a contact or lead.
A conversation request is the start of a call on an extension.
There can be multiple conversations in one call (in case of call transfer).
Short description of customizations
№
Customization file (alphabetically)
Description
1
customize_activity.php
Update the case fields (at the end of the call).
2
customize_entity.php
Update entity fields (at the end of the call).
3
need_registration.php
Is call registration necessary? You can do black/white lists by extension number/trunk.
4
process_client_phone.php
Change phone number before registration in CRM: You can change the format of the phone number (+7, 8...).
5
process_final_params.php
Change the call finish data.
6
process_originate_params.php
Change parameters when initiating a call from CRM. You can call through a different trunk, through a different context, change the number format, etc.
7
process_record_file_path.php
Customize the path to the conversation recording file.
8
process_registration_params.php
Change the call registration parameters.
9
process_task_creation_params.php
Customize the creation of missed call tasks.
10
process_user_phone.php
Change the user number before searching for the user in B24.
11
customize_autodistribution.php
Change the extension number when autodistributing an incoming call.
12
post_registration.php
Action after call registration.
13
customize_show_call_card.php
Change the display options for the call card.
14
customize_attach_record_url.php
Change the record attachment settings.
Input and output parameters of customizations
1) customize_activity
Input:
{
<Set of conversation data (conversation, saved for backward compatibility)>,
"activity": {
"id":"<ID of case>"
"is_new": <Always false>,
"name": "<Name of case (from SUBJECT field)>",
"phones": [<All times empty array>],
"raw": { "case fields as in Bitrix24"],
"responsible": {<Responsible User Data>},
"responsible_id": "<ID of responsible user>",
"type": "activity"
},
"call_full": {<Full set of call data>}
}
Only non-empty/non-zero fields are present in the raw object.
Return:
{
"data": {
"<The name of the case field in Bitrix>": "<Value of this field>",
...
},
"state": "success"
}
Used to implement black/white list functionality by numbers, trunks and other more complex conditions.
Basic black/white list configuration for internal numbers is available from the admin panel (configuration interface) of the connector.
Input:
{
"call_full": {<Full set of call data>},
"call_stage": "<Call Stage. For this customization one of the options is:
conversation_requested - conversation request;
conversation_accepted - response;
conversation_ended - end of conversation;
call_ended - call end>"
<The remaining fields have been retained for backward compatibility>
}
{
"phone": "<number>",
"call_full": {<Full set of call data>},
"call_stage": "<Call Stage. For this customization one of the options is:
conversation_requested - conversation request;
conversation_accepted - response;
conversation_ended - end of conversation;
call_ended - call end>"
}
Customization of call registration completion parameters.
Input:
{
"ADD_TO_CHAT": <[0/1] Whether to add a call message to the business chat.
Default 1>,
"CALL_ID": "<ID call in Bitrix24. It is not recommended to change it!>",
"DURATION": <Call duration in seconds>,
"STATUS_CODE": "<Call status in Bitrix24>",
"USER_ID": <ID Bitrix24 user responsible for the conversation>,
"call_full": {<Full set of call data>},
<The remaining fields have been retained for backward compatibility>
}
{
"data": {
"ADD_TO_CHAT": <[0/1] Whether to add a call message to the business chat room>,
"CALL_ID": "<ID call in Bitrix24. It is not recommended to change it!>",
"DURATION": <Call duration in seconds>,
"STATUS_CODE": "<Call status in Bitrix24>",
"USER_ID": <ID Bitrix24 user responsible for the conversation>
},
"state": "success"
}
Convert the path to the conversation recording file.
When installing Itgrix_bx, conversion of call recording files to mp3 format before sending to Bitrix24 is already enabled by default. This allows you to:
Save space on Bitrix24 disk (mp3 takes less space than wav);
Listen to the recordings using the built-in CRM player.
Since conversion of records can take considerable time, this customization has a special, fixed timeout of 10 seconds, which does not depend on the customization settings. If the record fails to convert before the timeout expires, the original file will be used.
8) process_registration_params
Used to customize the call start registration parameters.
Input:
{
"CALL_START_DATE": "<Date-time of the start of the call>",
"CRM_CREATE": <[0/1] Whether or not to create a new lead (if the number is not found in CRM)>,
"CRM_SOURCE": "<STATUS_ID source from the source directory>",
"LINE_NUMBER": "<External line number in Bitrix24 through which the call was made>",
"PHONE_NUMBER": "<Number for entity lookup in bitrix>",
"SHOW": <[0/1] Whether to show a call card when registering>,
"TYPE": <Call direction: 1 - outgoing, 2 - incoming>,
"USER_ID": <user ID>,
"call_full": {<Full set of call data>},
"call_stage": "<Call Stage. For this customization one of the options is:
conversation_requested - conversation request;
call_ended - call end>",
<The remaining fields have been retained for backward compatibility>
}
External line numbers in Bitrix24 (LINE_NUMBER) correspond to trunks in Itgrix connector settings.
The connector registers trunk numbers as external lines in Bitrix24 at startup, and each line can be given a name in the settings.
Call card display is placed in a separate request and is customized by a separate customize_show_call_card customization, so the SHOW parameter is always 0.
This is because you can customize whether to show the call card when dialing or when answering.
Return:
{
"data": {
"CALL_START_DATE": "<Date-time of the start of the call>",
"CRM_CREATE": <[0/1] Whether or not to create a new lead (if the number is not found in CRM)>,
"CRM_SOURCE": "<STATUS_ID source from the source directory>",
"LINE_NUMBER": "<External line number in Bitrix24 through which the call was made>",
"PHONE_NUMBER": "<Number for entity lookup in bitrix>",
"SHOW": <[0/1] Whether to show a call card when registering>,
"TYPE": <Call direction: 1 - outgoing, 2 - incoming>,
"USER_ID": <user ID>
},
"state": "success"
}
Customization of task creation parameters (on missed incoming call or unanswered outgoing call).
This customization works only if task creation is enabled in the Connector settings.
In this case, the settings described in the article are applied first, and then this customization is performed.
Input:
{
"fields": {
"CREATED_BY": <ID director>,
"DEADLINE": "<Deadline for implementation>",
"RESPONSIBLE_ID": <ID the person responsible for the task>,
"TITLE": "<Task title>",
"UF_CRM_TASK": ["<ID entities in a customized format:
<Entity type>_<ID>.
Entity types:
lead - L
contact - C,
company - CO,
case - D.
Example: L_11201 for lead with ID 11201 >"]
},
"call_full": {<Full set of call data>},
<The remaining fields have been retained for backward compatibility>
}
Return:
{
"data": {
"fields": {
"<Task field name in Bitrix>": "<The value of this field is>"
...
}
},
"state": "success"
}
Change the user number before searching for a Bitrix24 user.
Auto number replacement is available, it is started BEFORE customization is performed.
Input:
{
"phone": "<номер>",
"call_full": {<Full set of call data>},
"call_stage": "<Call Stage. For this customization one of the options is:
conversation_requested - conversation request;
conversation_accepted - response;
conversation_ended - end of conversation;
call_ended - call end>"
}
{
"number": "<the number of the user to whom the call should be distributed>",
"name": "<the name of the user to whom the call should be distributed>",
"from": "<calling number>",
"user": {
"id": <User ID numberм>,
"phones": ["<user phone number list>"],
"name": "<Full user name>",
"email": "<user email>",
"position": "<user post>"
},
"entity": {
"type": "<Entity type in text, e.g. lead, contact>",
"id": <Entity ID by number>,
"name": "<Entity Name>",
"responsible_id": <Responsible user ID by number>
},
"error": "<error text>"
}
Return:
{
"data": {
"number": "<the number of the user to whom the call should be distributed>",
"name": "<the name of the user to whom the call should be distributed>"
},
"state": "success"
}
name - text that will appear in CallerID and will be displayed in the phone (or softphone) of the operator.
Must be no more than 20 characters (Asterisk limitation)!
The from, user, entity and error fields are read-only and are only present when not empty.
They will be automatically deleted even if you return them in the data object.
12) post_registration
This customization allows you to perform some actions after a call is registered.
It can be called at different moments depending on the type of call:
For click-to-call (c2c) calls, the customization will be invoked at the beginning of the Conversation requested stage processing.
During click calls Bitrix24 itself registers the call at the moment of click and passes the registration data to the connector, i.e. before the call is initialized in Asterisk.
That is why, the connector itself does NOT register click calls, but only terminates them like all other calls.
Missed calls on the IVR are logged and terminated at the Call ended stage.
For all other calls, the customization will be invoked after the call registration request is executed in Bitrix24 at the Conversation requested stage.
Input:
{
"call_full": {<Full set of call data>},
"call_stage": "<Call Stage. For this customization one of the options is:
conversation_requested - conversation request;
call_ended - call end>",
}
Return:
Only state needs to be returned, the rest is ignored:
{
"state": "success"
}
13) customize_show_call_card
Used to customize call card display options.
Input:
{
"CALL_ID": <ID of a registered call in Bitrix24>,
"USER_ID": <user ID>,
"call_full": {<Full set of call data>},
"call_stage": "<Call Stage. For this customization one of the options is:
conversation_requested - conversation request;
conversation_accepted - response;
conversation_ended - end of conversation;
call_ended - call end>"
}
Return:
{
"data": {
"CALL_ID": <ID of a registered call in Bitrix24>,
"USER_ID": <user ID>
},
"state": "success"
}
Customization of attaching a link to a call recording. Runs only if it is configured to attach a link to a record instead of a call record file.
By default, the HTML code of the audio player (audio tag) with a link to the call record is written to the case description.
Input:
{
"DESCRIPTION": "<Case description with audio player and link to call recording>",
"DESCRIPTION_TYPE": <Content type as an integer, default is 3, i.e. HTML>,
"activity": {
"id": "<case ID>",
"is_new": <Always false>,
"name": "<Case name (from SUBJECT field)>",
"phones": [<Always an empty array>],
"raw": {Case fields as in Bitrix24},
"responsible": {<Data of the responsible user>},
"responsible_id": "<Responsible user ID>",
"type": "activity"
},
"call_full": {<Full set of call data>}
}
Only non-empty/non-zero fields are present in the raw object.
Return:
{
"data": {
"<The name of the case field in Bitrix>":"<Value of this field>",
...
},
"state": "success"
}
