# Useful customizations itgrix\_kmo (Kommo)

## Call processing scheme by Itgrix integration module

(Scheme for versions starting from 3.0.0)

<div><img src="https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/.gitbook/assets/temp%20(1).png" alt=""> <figure><img src="https://1054546226-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M-rzZJr51tgvX7eVK8M%2Fuploads%2FDlaSmMpPhU3d5dTjBde5%2Fscheme3.0.0.png?alt=media&#x26;token=5534518a-5174-42a2-a545-885078b2c4cf" alt=""><figcaption></figcaption></figure></div>

"Request a conversation" - when the phone rings at the employee / client.\
There can be several "conversations" in one "call" (in case of call transfer).

## Brief description of customizations

| №  | <p>Customization file<br>(in alphabetical order)</p>                                                                            | Description                                                                                                                                                                                                                                                             |
| -- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1  | [need\_registration.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)                 | Is it necessary to register the call? It is possible to make black/white lists by internal number/trunk.                                                                                                                                                                |
| 2  | [process\_call\_params.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)              | Change the call registration parameters.                                                                                                                                                                                                                                |
| 3  | [process\_client\_phone.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)             | Change your phone number before registering to CRM. You can change the format of your phone number (+7, 8...).                                                                                                                                                          |
| 4  | [process\_contact\_creation\_params.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md) | Change the settings for creating a contact.                                                                                                                                                                                                                             |
| 5  | [process\_lead\_creation\_params.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)    | Changing the parameters for creating a deal.                                                                                                                                                                                                                            |
| 6  | [process\_originate\_params.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)         | Changing parameters when initiating a call from CRM. You can call through another trunk, through another context, change the number format, and so on.                                                                                                                  |
| 7  | [process\_record\_file\_path.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)        | <p>Customizing the path to the conversation recording file. Also in this file, converting from wav to mp3 format is configured.</p><p>Description <a href="for-admins/converting-recordings-to-mp3-before-sending-to-bitrix24">Converting record to mp3 format</a>.</p> |
| 8  | [process\_task\_creation\_params.php](https://gitlab.itgro.dev/itgrix/gitbookrus/-/blob/sync-eng/broken-reference/README.md)    | Changing the settings for creating tasks on missed calls. Changing the task name can interfere with the [automatic task completion option](https://docs.itgrix.ru/settings/additional/auto-mange-tasks#amocrm).                                                         |
| 9  | [customize\_autodistribution.php](https://docs.itgrix.ru/custom_amo#id-9-customize_autodistribution)                            | Customization of autodistribution of incoming calls.                                                                                                                                                                                                                    |
| 10 | [post\_registration.php](https://docs.itgrix.ru/custom_amo#id-10-post_registration)                                             | Actions after the call has been logged.                                                                                                                                                                                                                                 |
| 11 | [process\_contact\_update\_params.php](https://docs.itgrix.ru/custom_amo#id-11-process_contact_update_params)                   | Change the contact's update settings.                                                                                                                                                                                                                                   |
| 12 | [process\_lead\_update\_params.php](https://docs.itgrix.ru/custom_amo#id-12-process_lead_update_params)                         | Change the lead's  update settings.                                                                                                                                                                                                                                     |
| 13 | [process\_unsorted\_creation\_params.php](https://docs.itgrix.ru/custom_amo#id-13-process_unsorted_creation_params)             | Changes the parameters for creating unsorted. Allows you to change the contact and lead fields.                                                                                                                                                                         |

## Input and output parameters of customizations

### **1) need\_registration**

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

{% hint style="info" %}
Basic black/white list configuration for internal numbers is available from the admin panel.
{% endhint %}

Examples: Black/white list for trunks.

**Input:**

```json
{
  "call_full": {<Full call data set>},
  "call_stage": "<Call Stage. For this customization one of the options is:
     conversation_requested - call request;
     conversation_accepted  - answer;
     conversation_ended     - end of conversation;
     call_ended             - call end>"
}
```

The full set of call data is described in the article Call data (call\_full) in customizations.

**Return:**

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

### **2) process\_call\_params**

Changing call registration parameters.

{% hint style="info" %}
Read more about call statuses (call\_status and call\_result fields) in the article Detailed call statuses.
{% endhint %}

**Input:**

```javascript
{
  "call_full": {<Full call data set>},
  
  "call_result": "<Call result>",
  "call_status": <Call Status>,
  "created_at": <Date the call was created (in Unix Timestamp format)>,
  "created_by": <responsible user ID>,
  "direction": "<Call Direction. Values:
                "inbound" - incoming, "outbound" - outgoing>",
  "duration": <Duration (of the last call) in seconds>,
  "link": "<Link to get the recording (of the last conversation)>",
  "phone": "<Client's phone number
            (already customized via process_client_phone)>",
  "responsible_user_id": <responsible user ID>,
  "source": "itgrix_amo"
}
```

The full set of call data is described in the article Call data (call\_full) in customizations.

**Return:**

```javascript
{
  "data": {
    "call_result": "<Call result>",
    "call_status": <Call Status>,
    "created_at": <Date the call was created (in Unix Timestamp format)>,
    "created_by": <responsible user ID>,
    "direction": "<Call Direction. Values:
                    "inbound" - incoming, "outbound" - outgoing>",
    "duration": <Duration (of the last call) in seconds>,
    "link": "<Link to get the recording (of the last conversation)>",
    "phone": "<Client's phone number
                (already customized via process_client_phone)>",
    "responsible_user_id": <responsible user ID>,
    "source": "itgrix_amo"
  },
  "state": "success"
}
```

### **3) process\_client\_phone**

Converting client phone numbers before sending requests to amoCRM.

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

Examples in the article Changing customer number before sending to CRM.

**Input:**

```json
{
  "phone": "<номер>",
  
  "call_full": {<Full call data set>},
  "call_stage": "<Call Stage. For this customization one of the options is:
     conversation_requested - call request;
     conversation_accepted  - answer;
     conversation_ended     - end of conversation;
     call_ended             - call end>"
}
```

**Return:**

```json
{
  "data": {
    "phone": "<Customized number>"
  },
  "state": "success"
}
```

### **4) process\_contact\_creation\_params**

Changing contact creation parameters.

{% hint style="info" %}
In Kommo, by default, there is no field for a phone number in a contact. Instead, custom contact fields are used.

Itgrix\_kmo works with the contact field `"code": "PHONE"` at the available value `"enum": "WORK"`. **If there is no such field for contacts in the account, the module will not run.**

Detailed description of custom fields in [Kommo API documentation](https://developers.kommo.com/reference/custom-fields).
{% endhint %}

**Example**: Changing the tag when creating a contact/dea&#x6C;**.**

**Input:**

```javascript
{
  "call_full": {<Full call data set>},

  "custom_fields_values": [
    {
      "field_id": <ID of the custom contact field in the account
                   (retrieved automatically)>,
      "values": [
        {
          "enum_code": "<Field value.
                        Itgrix works with the value "WORK">",
          "value": "<Phone number of the caller>"
        }
      ]
    }
  ],
  "name": "<Contact Name. Default "Contact <Phone number>">",
  "responsible_user_id": <Responsible user ID>,
  "tags": [
    "Itgrix"
  ]
}
```

**Return:**

```javascript
{
  "data": {
    "custom_fields_values": [
      {
        "field_id": <ID of the custom contact field in the account
                    (retrieved automatically)>,
        "values": [
          {
            "enum_code": "<Field value.
                          Itgrix works with the value "WORK">",
            "value": "<Phone number of the caller>"
          }
        ]
      }
    ],
    "name": "<Contact Name. Default "Contact <Phone number>">",
    "responsible_user_id": <Responsible user ID>,
    "tags": [
      "Itgrix"
    ]
    
    // Other fields can also be set
  },
  "state": "success"
}
```

The parameters of the contact creation request are described in the [Kommo API documentation](https://developers.kommo.com/reference/add-contacts).

### **5) process\_lead\_creation\_params**

Changing the parameters for lead creating.

Example: Changing the tag when creating a contact/lead.

**Input:**

```javascript
{
  "call_full": {<Full call data set>},
  
  "_embedded": {
    "contacts": [
      {"id": <Contact ID to which the lead is linked>}
    ],
    "tags": [
      {"name": "Itgrix"}
    ]
  },
  "name": "<Lead title.
          By default "<Phone number> - [missed] incoming/outgoing">",
  "pipeline_id": <Lead funnel ID>,
  "responsible_user_id": <Responsible user ID>,
  "status_id": <ID of the status to which the lead is added>
}
```

**Return:**

```javascript
{
  "data": {
    "_embedded": {
      "contacts": [
        {"id": <Contact ID to which the lead is linked>}
      ],
      "tags": [
        {"name": "Itgrix"}
      ]
    },
    "name": "<Lead title.
          By default "<Phone number> - [missed] incoming/outgoing">",
    "pipeline_id": <Lead funnel ID>,
    "responsible_user_id": <Responsible user ID>,
    "status_id": <ID of the status to which the lead is added>
    
    // Other fields can also be set
  },
  "state": "success"
}
```

The parameters of the transaction creation request are described in the [Kommo API documentation](https://developers.kommo.com/reference/adding-leads).

### **6) process\_originate\_params**

Changing parameters at call initialization from Kommo.

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

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

Converting the path to a call recording file.

Detailed description with examples in the article Customizing audio file name.

{% hint style="info" %}
When registering a call in amoCRM, a player will be added to the note to play a recording of that call (via a link that the Itgrix module adds automatically). But the player only supports mp3 format.

Conversion of call recording files to mp3 is already enabled by default when installing Itgrix\_kmo.
{% endhint %}

{% hint style="warning" %}
Since conversion of records can take considerable time, this customization has an individual timeout of 10 seconds (can be changed in the connector configuration file - `/etc/itgrix_amo/config.json`).

If the record fails to convert before the timeout expires, the original file will be used.
{% endhint %}

### **8) 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.

This customization is done after applying settings from the admin area..
{% endhint %}

**Input:**

```javascript
{
  "call_full": {<Full call data set>},
  
  "complete_till": <Date-Time when the task is to be completed
                    (in Unix Timestamp format)>,
  "created_by": <ID of the user creating the task>,
  "entity_id": <ID of the entity to which the task is bound>,
  "entity_type": "<Type of entity to which the task is bound.
                  Takes values: "contacts", "leads">",
  "is_completed": <Whether the task is completed. When created, always false>,
  "responsible_user_id": <Responsible user ID>,
  "task_type": <Task Type. Numerical value:
                1 - Call, 2 - Meet, 3 - Email>,
  "text": "<Task Description. Default:
           "Call back <Entity name> on a missed call from a number <Phone number>">"
}
```

**Return:**

```javascript
{
  "data": {
    "complete_till": <Date-Time when the task is to be completed
                      (in Unix Timestamp format)>,
    "created_by": <ID of the user creating the task>,
    "entity_id": <ID of the entity to which the task is bound>,
    "entity_type": "<Type of entity to which the task is bound.
                    Takes values: "contacts", "leads">",
    "is_completed": <Whether the task is completed. When created, always false>,
    "responsible_user_id": <Responsible user ID>,
    "task_type": <Task Type. Numerical value:
                  1 - Call, 2 - Meet, 3 - Email>,
    "text": "<Task Description. Default:
             "Call back <Entity name> on a missed call from a number <Phone number>">"

    // Other fields can also be set
  },
  "state": "success"
}
```

Parameters of the task creation request are described in the [Kommo API documentation](https://developers.kommo.com/reference/add-tasks).

### 9) customize\_autodistribution

Customization of autodistribution of incoming calls.

{% hint style="info" %}
For the auto-distribution function to work, it is necessary to configure Asterisk, described in the article Auto-distribute a call to the responsible manager.
{% endhint %}

**Input:**

```json
{
  "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>",
  "trunk": "<Trunk number>",
  "request_data": {<Parameters of autodistribution request as is>},
  "entity": {<Found entity data>},
  "error": "<error message>"
}
```

**Return:**

```json
{
  "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` - the text that will appear in CallerID and will be displayed in the operator's phone (or softphone).

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

{% hint style="info" %}
Fields `from`, `trunk`, `entity` and `error` - are read-only and only present when not empty.

These fields, as well as `request_data` will be automatically deleted even if you return them in the object `data`.
{% endhint %}

### 10) post\_registration

This customization gives you the option to perform any actions after the call is registered.

**Input:**

```json
{
  "call_full": {<Full call data set>}
}
```

**Return:**

The only thing that needs to be returned `state`, the other things are ignored.:

```json
{
  "state": "success"
}
```

### 11) process\_contact\_update\_params

Changing contact update settings.

**Input:**

```json
{
  "call_full": {<Full call data set>},
  
  "id": <Contact ID>,
  "responsible_user_id": <Responsible user ID>
}
```

**Вернуть:**

```json
{
  "data": {
    "id": <Contact ID>,
    "responsible_user_id": <Responsible user ID>

    // Other fields can also be set
  },
  "state": "success"
}
```

The parameters of the contact update request are described in the [Kommo API documentation](https://developers.kommo.com/reference/update-contacts).

### 12) process\_lead\_update\_params

Changing the parameters of lead update.

**Input:**

```json
{
  "call_full": {<Full call data set>},
  
  "id": <Lead ID>,
  "responsible_user_id": <Responsible user ID>
}
```

**Return:**

```json
{
  "data": {
    "id": <Lead ID>,
    "responsible_user_id": <Responsible user ID>

    // Other fields can also be set
  },
  "state": "success"
}
```

Parameters of transaction update request are described in [Kommo API documentation](https://developers.kommo.com/reference/updating-single-lead).

### 13) process\_unsorted\_creation\_params

Changes the parameters for creating an unassembled. Allows you to change the contact and transaction fields.

**Input:**

```json
{
  "call_full": {<Full call data set>},

  "_embedded": {
    "contacts": [{
      "custom_fields_values": [{
        "field_id": <ID of the custom contact field in the account
                    (retrieved automatically)>,
        "values": [{
          "enum_code": "<Field value.
                        Itgrix works with the value "WORK">",
          "value": "<Phone number of the caller>"
        }]
      }],
      "name": "<Contact Name. Default "Contact <Phone number>">",
      "tags": [
        "Itgrix"
      ]
    }],
    "leads": [{
      "name": "<Lead title.
               By default "<Phone number> - [missed] incoming/outgoing">",
      "pipeline_id": <Lead funnel ID>,
      "tags": [
        {"name": "Itgrix"},
      ]
    }]
  },
  "created_at": <Date of unsorted creation (in Unix Timestamp format)>,
  "metadata": {
    "called_at": <When the call was made (in Unix Timestamp format)>,
    "duration": <Call duration in seconds>,
    "from": "<Calling number>",
    "is_call_event_needed": false,
    "link": "<Call recording link>",
    "phone": "<The phone number that was called>",
    "service_code": "itgrix_amo",
    "uniq": "<Unique call ID.
              Itgrix is sending linkedid>"
  },
  "pipeline_id": <Lead funnel ID>,
  "source_name": "itgrix_amo",
  "source_uid": "<UID of request source.
                  Itgrix is sending linkedid>"
}
```

**Return:**

```json
{
  "data": {
    "_embedded": {
      "contacts": [{
        "custom_fields_values": [{
          "field_id": <ID of the custom contact field in the account
                      (retrieved automatically)>,
          "values": [{
            "enum_code": "<Field value.
                          Itgrix works with the value "WORK">",
            "value": "<Phone number of the caller>"
          }]
        }],
        "name": "<Contact Name. Default "Contact <Phone number>">",
        "tags": [
          "Itgrix"
        ]
      }],
      "leads": [{
        "name": "<Lead title.
                By default "<Phone number> - [missed] incoming/outgoing">",
        "pipeline_id": <Lead funnel ID>,
        "tags": [
          {"name": "Itgrix"},
        ]
      }]
    },
    "created_at": <Date of unsorted creation (in Unix Timestamp format>,
    "metadata": {
      "called_at": <When the call was made (in Unix Timestamp format)>,
      "duration": <Call duration in seconds>,
      "from": "<Calling number>",
      "is_call_event_needed": false,
      "link": "<Call recording link>",
      "phone": "<The phone number that was called>",
      "service_code": "itgrix_amo",
      "uniq": "<Unique call ID.
                Itgrix is sending linkedid>"
    },
    "pipeline_id": <Lead funnel ID>,
    "source_name": "itgrix_amo",
    "source_uid": "<UID of request source.
                    Itgrix is sending linkedid>"

    // Other fields can also be set
  },
  "state": "success"
}
```