Useful customizations itgrix_bx (Bitrix24)

Diagram of call processing by Itgrix integration module

Version 3.10+ customizations

"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"
}

Detailed description of the case fields in Bitrix24 REST API documentation.

2) customize entity

Input:

{
  "call_full": {<Full set of call data>},
  <The remaining fields have been retained for backward compatibility>
}

Return:

{
  "data": {
    "<Entity field name in Bitrix>": "<The value of this field>",
    ...
  },
  "state": "success"
}

Detailed description of lead fields in Bitrix24 REST API documentation. Detailed description of contact fields in Bitrix24 REST API documentation.

3) need registration

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>
}

Return:

{
  "data": {
    "result": <true - register; false - ignore>
  },
  "state": "success"
}

4) process_client_phone

Converting customer phone numbers before sending requests to Bitrix24.

Examples in the article Changing the phone number before sending data to CRM.

Input:

{
  "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>"
}

Return:

{
  "data": {
    "phone": “<Customized number>”
  },
  "state": "success"
}

5) process_final_params

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>
}

Call statuses in Bitrix24 are described in the article Detailed call statuses.

Return:

{
  "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"
}

Detailed description of call termination parameters in Bitrix24 REST API documentation.

6) process_originate_params

Changing parameters when initializing a call from Bitrix24.

Detailed description with examples in the article Changing parameters during click-to-call.

7) process_record_file_path

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:

1. Save space on Bitrix24 disk (mp3 takes less space than wav);

2. 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"
}

Detailed description of call registration parameters in Bitrix24 REST API documentation.

9) process_task_creation_params

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"
}

Detailed description of task fields in Bitrix24 REST API documentation.

10) process_user_phone

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>"
}

Return:

{
  "data": {
    "phone": "<customized_number>"
  },
  "state": "success"
}

11) customize_autodistribution

Input:

{
  "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"
}

Detailed description of card display parameters in Bitrix24 REST API documentation.

14) customize_attach_record_url

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"
}

Detailed description of the case fields in Bitrix24 REST API documentation.