# Useful customizations itgrix\_bx (Bitrix24)

## Diagram of call processing by Itgrix integration module

<figure><img src="https://1054546226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M-rzZJr51tgvX7eVK8M%2Fuploads%2FjrjfFMzXY1ACoznvNkML%2FlogicScheme.png?alt=media&#x26;token=5a706357-85f0-4abc-96a4-30ed59913075" alt=""><figcaption><p>Version 3.10+ customizations</p></figcaption></figure>

"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

<table data-full-width="false"><thead><tr><th>№</th><th width="305">Customization file (alphabetically)</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>customize_activity.php</td><td>Update the case fields (at the end of the call).</td></tr><tr><td>2</td><td>customize_entity.php</td><td>Update entity fields (at the end of the call).</td></tr><tr><td>3</td><td>need_registration.php</td><td>Is call registration necessary? You can do black/white lists by extension number/trunk.</td></tr><tr><td>4</td><td>process_client_phone.php</td><td>Change phone number before registration in CRM: You can change the format of the phone number (+7, 8...).</td></tr><tr><td>5</td><td>process_final_params.php</td><td>Change the call finish data.</td></tr><tr><td>6</td><td>process_originate_params.php</td><td>Change parameters when initiating a call from CRM. You can call through a different trunk, through a different context, change the number format, etc.</td></tr><tr><td>7</td><td>process_record_file_path.php</td><td>Customize the path to the conversation recording file.</td></tr><tr><td>8</td><td>process_registration_params.php</td><td>Change the call registration parameters.</td></tr><tr><td>9</td><td>process_task_creation_params.php</td><td>Customize the creation of missed call tasks.</td></tr><tr><td>10</td><td>process_user_phone.php</td><td>Change the user number before searching for the user in B24.</td></tr><tr><td>11</td><td>customize_autodistribution.php</td><td>Change the extension number when autodistributing an incoming call.</td></tr><tr><td>12</td><td>post_registration.php</td><td>Action after call registration.</td></tr><tr><td>13</td><td>customize_show_call_card.php</td><td>Change the display options for the call card.</td></tr><tr><td>14</td><td>customize_attach_record_url.php</td><td>Change the record attachment settings.</td></tr></tbody></table>

## Input and output parameters of customizations

### **1)** customize\_activity

**Input:**

```php
{
  <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>}
}
```

{% hint style="warning" %}
Only non-empty/non-zero fields are present in the raw object.
{% endhint %}

**Return:**

```php
{
  "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](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_fields.php).

### 2) customize entity

**Input:**

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

**Return:**

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

Detailed description of lead fields in [Bitrix24 REST API documentation](https://training.bitrix24.com/rest_help/crm/leads/crm_lead_fields.php). \
Detailed description of contact fields in [Bitrix24 REST API documentation](https://training.bitrix24.com/rest_help/crm/contacts/crm_contact_fields.php).

### 3) need registration

Used to implement black/white list functionality by numbers, trunks and other more complex conditions.

{% hint style="info" %}
Basic [black/white list](https://docs.itgrix.com/custom_common/black-and-white-lists) configuration for internal numbers is available from the admin panel (configuration interface) of the connector.
{% endhint %}

**Input:**

```php
{
  "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:**

```php
{
  "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](https://docs.itgrix.com/custom_common/change-phone-number-before-sending-data-to-crm).

**Input:**

```php
{
  "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:**

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

### 5) process\_final\_params

Customization of call registration completion parameters.

**Input:**

```php
{
  "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](https://docs.itgrix.com/faq/detail-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](https://training.bitrix24.com/rest_help/scope_telephony/telephony/telephony_externalcall_finish.php).

### 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](https://docs.itgrix.com/custom_common/change-the-number-context-for-calling-to-asterisk).

### 7) **process\_record\_file\_path**

Convert the path to the conversation recording file.

{% hint style="info" %}
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**:&#x20;

1. Save space on Bitrix24 disk (mp3 takes less space than wav);&#x20;
2. Listen to the recordings using the built-in CRM player.
   {% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

### 8) **process\_registration\_params**

Used to customize the call start registration parameters.

**Input:**

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

{% hint style="info" %}
External line numbers in Bitrix24 (LINE\_NUMBER) correspond to trunks in Itgrix connector settings.&#x20;

The connector registers trunk numbers as external lines in Bitrix24 at startup, and each line can be given a name in the settings.
{% endhint %}

{% hint style="warning" %}
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**.&#x20;

This is because you can customize whether to show the call card when dialing or when answering.
{% endhint %}

**Return:**

```php
{
  "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](https://training.bitrix24.com/rest_help/scope_telephony/telephony/telephony_externalcall_register.php).

### 9) **process\_task\_creation\_params**

Customization of task creation parameters (on missed incoming call or unanswered outgoing call).

{% hint style="info" %}
This customization works only if task creation is enabled in the Connector settings.&#x20;

In this case, the settings described in the article are applied first, and then this customization is performed.
{% endhint %}

**Input:**

```php
{
  "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:**

```php
{
  "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](https://training.bitrix24.com/rest_help/tasks/fields.php).

### **10) process\_user\_phone**

Change the user number before searching for a Bitrix24 user.

{% hint style="info" %}
Auto number replacement is available, it is started BEFORE customization is performed.
{% endhint %}

**Input:**

```php
{
  "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:**

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

### 11) **customize\_autodistribution**

**Input:**

```php
{
  "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:**

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

{% hint style="warning" %}
*name* - text that will appear in CallerID and will be displayed in the phone (or softphone) of the operator.&#x20;

**Must be no more than 20 characters (Asterisk limitation)!**
{% endhint %}

{% hint style="info" %}
The *from*, *user*, *entity* and error fields are read-only and are only present when not empty.&#x20;

They will be automatically deleted even if you return them in the data object.
{% endhint %}

### 12) post\_registration

This customization allows you to perform some actions after a call is registered.&#x20;

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.

{% hint style="info" %}
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.&#x20;

That is why, the connector itself does NOT register click calls, but only terminates them like all other calls.
{% endhint %}

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

```php
{
  "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:

```php
{
  "state": "success"
}
```

### 13) customize\_show\_call\_card

Used to customize call card display options.

**Input:**

```php
{
  "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:**

```php
{
  "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](https://training.bitrix24.com/rest_help/scope_telephony/telephony/telephony_externalcall_show.php).

### 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.&#x20;

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:

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

{% hint style="warning" %}
Only non-empty/non-zero fields are present in the raw object.
{% endhint %}

**Return:**

```php
{
  "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](https://training.bitrix24.com/rest_help/crm/rest_activity/crm_activity_fields.php).