Useful customizations itgrix_kmo (Kommo)

Since version 3.0.0.

Call processing scheme by Itgrix integration module

(Scheme for versions starting from 3.0.0)

"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

№	Customization file (in alphabetical order)	Description
1	need_registration.php	Is it necessary to register the call? It is possible to make black/white lists by internal number/trunk.
2	process_call_params.php	Change the call registration parameters.
3	process_client_phone.php	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	Change the settings for creating a contact.
5	process_lead_creation_params.php	Changing the parameters for creating a deal.
6	process_originate_params.php	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	Customizing the path to the conversation recording file. Also in this file, converting from wav to mp3 format is configured. Description Converting record to mp3 format.
8	process_task_creation_params.php	Changing the settings for creating tasks on missed calls. Changing the task name can interfere with the automatic task completion option.
9	customize_autodistribution.php	Customization of autodistribution of incoming calls.
10	post_registration.php	Actions after the call has been logged.
11	process_contact_update_params.php	Change the contact's update settings.
12	process_lead_update_params.php	Change the lead's update settings.
13	process_unsorted_creation_params.php	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.

Basic black/white list configuration for internal numbers is available from the admin panel.

Examples: Black/white list for trunks.

Input:

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

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

2) process_call_params

Changing call registration parameters.

Read more about call statuses (call_status and call_result fields) in the article Detailed call statuses.

Input:

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

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

Auto number change is available, it is started BEFORE customization is performed.

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

Input:

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

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

4) process_contact_creation_params

Changing contact creation parameters.

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.

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

Input:

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

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

5) process_lead_creation_params

Changing the parameters for lead creating.

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

Input:

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

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

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.

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.

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.

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

This customization is done after applying settings from the admin area..

Input:

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

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

9) customize_autodistribution

Customization of autodistribution of incoming calls.

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.

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

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 - 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)!

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.

10) post_registration

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

Input:

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

Return:

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

{
  "state": "success"
}

11) process_contact_update_params

Changing contact update settings.

Input:

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

Вернуть:

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

12) process_lead_update_params

Changing the parameters of lead update.

Input:

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

Return:

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

13) process_unsorted_creation_params

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

Input:

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

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