Полезные кастомизации itgrix_amo (amoCRM)

Начиная с версии 3.0.0.

Дополнительные кастомизации описаны в разделе Полезные кастомизации (любая CRM).

Схема обработки звонка модулем интеграции Itgrix

(Схема для версий начиная с 3.0.0)

"Запрос разговора" – когда звонит телефон у сотрудника/клиента. В одном "звонке" может быть несколько "разговоров" (в случае перевода звонка).

Краткое описание кастомизаций

№	Файл кастомизации (по алфавиту)	Описание
1	need_registration.php	Нужна ли регистрация звонка? Можно сделать черные/белые списки по внутреннему номеру/транку.
2	process_call_params.php	Изменение параметров регистрации звонка.
3	process_client_phone.php	Изменение номера телефона перед регистрацией в CRM. Можно сменить формат телефонного номера (+7, 8...).
4	process_contact_creation_params.php	Изменение параметров создания контакта.
5	process_lead_creation_params.php	Изменение параметров создания сделки.
6	process_originate_params.php	Изменение параметров при инициализации звонка из CRM. Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.
7	process_record_file_path.php	Кастомизация пути до файла записи разговора. Также в этом файле настраивается конвертирование из формата wav в mp3. Описание в статье Конвертация записей в формат MP3.
8	process_task_creation_params.php	Изменение параметров создания задач по пропущенным звонкам. Изменение названия задачи может помешать опции автоматического завершения задач.
9	customize_autodistribution.php	Кастомизация автораспределения входящих звонков.
10	post_registration.php	Действия после регистрации звонка.
11	process_contact_update_params.php	Изменение параметров обновления контакта.
12	process_lead_update_params.php	Изменение параметров обновления сделки.
13	process_unsorted_creation_params.php	Изменение параметров создания неразобранного. Позволяет изменить поля контакта и сделки.

Входные и выходные параметры кастомизаций

1) need_registration

Используется для реализации функционала чёрных/белых список по номерам, транкам и прочим более сложным условиям.

Базовая настройка черного/белого списка для внутренних номеров доступна из админки (интерфейса настройки) коннектора.

Примеры: Черный/белый список для транков.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка>"
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "result": <true - регистрируем; false - игнорируем>
  },
  "state": "success"
}

2) process_call_params

Изменение параметров регистрации звонка.

Подробнее про статусы звонка (поля call_status и call_result) в статье Детальные статусы звонка.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},
  
  "call_result": "<Результат звонка>",
  "call_status": <Статус звонка>,
  "created_at": <Дата создания звонка (в формате Unix Timestamp)>,
  "created_by": <ID ответственного пользователя>,
  "direction": "<Направление звонка. Принимает значения:
                "inbound" - входящий, "outbound" - исходящий>",
  "duration": <Длительность (последнего разговора) в секундах>,
  "link": "<Ссылка на получение записи (последнего разговора)>",
  "phone": "<Телефонный номер клиента
            (уже кастомизированный через process_client_phone)>",
  "responsible_user_id": <ID ответственного пользователя>,
  "source": "itgrix_amo"
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "call_result": "<Результат звонка>",
    "call_status": <Статус звонка>,
    "created_at": <Дата создания звонка в Unix Timestamp>,
    "created_by": <ID ответственного пользователя>,
    "direction": "<Направление звонка. Принимает значения:
                    "inbound" - входящий, "outbound" - исходящий>",
    "duration": <Длительность (последнего разговора) в секундах>,
    "link": "<Ссылка на получение записи (последнего разговора)>",
    "phone": "<Телефонный номер клиента
                (уже кастомизированный через process_client_phone)>",
    "responsible_user_id": <ID ответственного пользователя>,
    "source": "itgrix_amo"
  },
  "state": "success"
}

3) process_client_phone

Преобразование телефонных номеров клиентов перед отправкой запросов в amoCRM.

Доступна автозамена номеров, она запускается ДО выполнения кастомизации.

Примеры в статье Изменение номера клиента перед отправкой в CRM.

Вход:

{
  "phone": "<номер>",
  
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка>"
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "phone": "<Кастомизированный номер>"
  },
  "state": "success"
}

4) process_contact_creation_params

Изменение параметров создания контакта.

В amoCRM по умолчанию в контакте нет поля для телефонного номера. Вместо этого используются пользовательские поля контактов.

Itgrix_amo работает с полем контактов "code": "PHONE" с доступным значением "enum": "WORK". Если такого поля для контактов в аккаунте нет, то модуль не запустится.

Подробное описание пользовательских полей в документации API amoCRM.

Пример: Изменение тега при создании контакта/сделки.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},

  "custom_fields_values": [
    {
      "field_id": <ID пользовательского поля контактов в аккаунте
                   (получено автоматически)>,
      "values": [
        {
          "enum_code": "<Значение поля.
                        Itgrix работает со значением "WORK">",
          "value": "<Номер телефона звонившего>"
        }
      ]
    }
  ],
  "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
  "responsible_user_id": <ID ответственного пользователя>,
  "tags": [
    "Itgrix"
  ]
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "custom_fields_values": [
      {
        "field_id": <ID пользовательского поля контактов в аккаунте
                    (получено автоматически)>,
        "values": [
          {
            "enum_code": "<Значение поля.
                          Itgrix работает со значением "WORK">",
            "value": "<Номер телефона звонившего>"
          }
        ]
      }
    ],
    "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
    "responsible_user_id": <ID ответственного пользователя>,
    "tags": [
      "Itgrix"
    ]
    
    // Прочие поля также можно установить
  },
  "state": "success"
}

Параметры запроса создания контакта описаны в документации API amoCRM.

5) process_lead_creation_params

Изменение параметров создания сделки.

Пример: Изменение тега при создании контакта/сделки.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},
  
  "_embedded": {
    "contacts": [
      {"id": <ID контакта, с которыми связана сделка>}
    ],
    "tags": [
      {"name": "Itgrix"}
    ]
  },
  "name": "<Название сделки.
          По умолчанию "<Тел.номер> - [пропущенный] входящий/исходящий">",
  "pipeline_id": <ID воронки сделок>,
  "responsible_user_id": <ID ответственного пользователя>,
  "status_id": <ID статуса, в который добавляется сделка>
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "_embedded": {
      "contacts": [
        {"id": <ID контакта, с которыми связана сделка>}
      ],
      "tags": [
        {"name": "Itgrix"}
      ]
    },
    "name": "<Название сделки.
            По умолчанию "<Тел.номер> - входящий/исходящий звонок">",
    "pipeline_id": <ID воронки сделок>,
    "responsible_user_id": <ID ответственного пользователя>,
    "status_id": <ID статуса, в который добавляется сделка>
    
    // Прочие поля также можно установить
  },
  "state": "success"
}

Параметры запроса создания сделки описаны в документации API amoCRM.

6) process_originate_params

Изменение параметров при инициализации звонка из amoCRM.

Подробное описание с примерами в статье Изменение параметров при click-to-call.

7) process_record_file_path

Преобразование пути до файла записи разговора.

Подробное описание с примерами в статье Кастомизация имени файла аудиозаписи.

При регистрации звонка в amoCRM в заметку будет добавлен плеер для проигрывания записи этого звонка (по ссылке, которую модуль Itgrix добавляет автоматически). Но плеер поддерживает только формат mp3.

При установке Itgrix_amo по умолчанию уже включена конвертация файлов записей разговоров в mp3.

Поскольку конвертация записей может занимать значительное время, у этой кастомизации индивидуальный таймаут 10 секунд (изменить можно в конфигурационном файле коннектора - /etc/itgrix_amo/config.json).

Если запись не успеет сконвертироваться до истечения таймаута, будет использован исходный файл.

8) process_task_creation_params

Кастомизация параметров создания задачи (при пропущенном входящем звонке или неотвеченном исходящем).

Данная кастомизация работает, только если создание задач включено в настройках коннектора: Настройка задачи по пропущенному через админку.

При этом сначала применяются настройки, описанные в статье, а затем выполняется данная кастомизация.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},
  
  "complete_till": <Дата-время, когда задача должна быть завершена
                    (в формате Unix Timestamp)>,
  "created_by": <ID пользователя, создающего задачу>,
  "entity_id": <ID сущности, к которой привязана задача>,
  "entity_type": "<Тип сущности, к которой привязана задача.
                  Принимает значения: "contacts", "leads">",
  "is_completed": <Выполнена ли задача. При создании всегда false>,
  "responsible_user_id": <ID ответственного пользователя>,
  "task_type": <Тип задачи. Числовое значение:
                1 - Звонок, 2 - Встреча, 3 - Письмо>,
  "text": "<Описание задачи. По умолчанию:
           "Перезвонить <Имя сущности> по пропущенному звонку с номера <Тел.номер>">"
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "complete_till": <Дата-время, когда задача должна быть завершена
                      (в формате Unix Timestamp)>,
    "created_by": <ID пользователя, создающего задачу>,
    "entity_id": <ID сущности, к которой привязана задача>,
    "entity_type": "<Тип сущности, к которой привязана задача.
                    Принимает значения: "contacts", "leads">",
    "is_completed": <Выполнена ли задача. При создании всегда false>,
    "responsible_user_id": <ID ответственного пользователя>,
    "task_type": <Тип задачи. Числовое значение:
                  1 - Звонок, 2 - Встреча, 3 - Письмо>,
    "text": "<Описание задачи. По умолчанию:
             "Перезвонить <Имя сущности> по пропущенному звонку с номера <Тел.номер>">"

    // Прочие поля также можно установить
  },
  "state": "success"
}

Параметры запроса создания задачи описаны в документации API amoCRM.

9) customize_autodistribution

Кастомизация автораспределения входящих звонков.

Для работы функции автораспределения необходимо выполнить настройку Asterisk, описанную в статье Автораспределение звонка на ответственного менеджера.

Вход:

{
  "number": "<номер пользователя на которого распределять звонок>",
  "name":   "<имя пользователя на которого распределять звонок>",

  "from": "<номер с которого пришёл звонок>",
  "trunk": "<Номер транка>",
  "request_data": {<Параметры запроса автораспределения как есть>},
  "entity": {<Данные найденной сущности>},
  "error": "<текст ошибки>"
}

Вернуть:

{
  "data": {
    "number": "<Номер пользователя, на которого распределять звонок>",
    "name":   "<Имя пользователя, на которого распределять звонок>"
  },
  "state": "success"
}

name - текст который появится в CallerID и будет отображен в телефоне (или софтфоне) оператора.

Должен быть не более 20 символов (ограничение Asterisk)!

Поля from, trunk, entity и error - только для чтения и присутствуют только когда не пустые.

Эти поля, а также request_data будут автоматически удалены, даже если вернуть их в объекте data.

10) post_registration

Данная кастомизация дает возможность выполнить какие-либо действия после регистрации звонка.

Вход:

{
  "call_full": {<Полный набор данных о звонке>}
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

Нужно вернуть только state, остальное игнорируется:

{
  "state": "success"
}

11) process_contact_update_params

Изменение параметров обновления контакта.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},
  
  "id": <ID контакта>,
  "responsible_user_id": <ID ответственного пользователя>
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "id": <ID контакта>,
    "responsible_user_id": <ID ответственного пользователя>

    // Прочие поля также можно изменить
  },
  "state": "success"
}

Параметры запроса обновления контакта описаны в документации API amoCRM.

12) process_lead_update_params

Изменение параметров обновления сделки.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},
  
  "id": <ID сделки>,
  "responsible_user_id": <ID ответственного пользователя>
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "id": <ID сделки>,
    "responsible_user_id": <ID ответственного пользователя>

    // Прочие поля также можно изменить
  },
  "state": "success"
}

Параметры запроса обновления сделки описаны в документации API amoCRM.

13) process_unsorted_creation_params

Изменение параметров создания неразобранного. Позволяет изменить поля контакта и сделки.

Вход:

{
  "call_full": {<Полный набор данных о звонке>},

  "_embedded": {
    "contacts": [{
      "custom_fields_values": [{
        "field_id": <ID пользовательского поля контактов в аккаунте
                    (получено автоматически)>,
        "values": [{
          "enum_code": "<Значение поля.
                        Itgrix работает со значением "WORK">",
          "value": "<Номер телефона звонившего>"
        }]
      }],
      "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
      "tags": [
        "Itgrix"
      ]
    }],
    "leads": [{
      "name": "<Название сделки.
               По умолчанию "<Тел.номер> - [пропущенный] входящий/исходящий">",
      "pipeline_id": <ID воронки сделок>,
      "tags": [
        {"name": "Itgrix"},
      ]
    }]
  },
  "created_at": <Дата создания неразобранного (в формате Unix Timestamp)>,
  "metadata": {
    "called_at": <Когда сделан звонок (в формате Unix Timestamp)>,
    "duration": <Длительность звонка в секундах>,
    "from": "<Номер телефона звонившего>",
    "is_call_event_needed": false,
    "link": "<Ссылка на запись звонка>",
    "phone": "<Номер телефона, на который звонили>",
    "service_code": "itgrix_amo",
    "uniq": "<Уникальный идентификатор звонка.
              Itgrix передает linkedid звонка>"
  },
  "pipeline_id": <ID воронки сделок>,
  "source_name": "itgrix_amo",
  "source_uid": "<UID источника заявки.
                  Itgrix передает linkedid звонка>"
}

Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.

Вернуть:

{
  "data": {
    "_embedded": {
      "contacts": [{
        "custom_fields_values": [{
          "field_id": <ID пользовательского поля контактов в аккаунте
                      (получено автоматически)>,
          "values": [{
            "enum_code": "<Значение поля.
                          Itgrix работает со значением "WORK">",
            "value": "<Номер телефона звонившего>"
          }]
        }],
        "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
        "tags": [
          "Itgrix"
        ]
      }],
      "leads": [{
        "name": "<Название сделки.
                По умолчанию "<Тел.номер> - [пропущенный] входящий/исходящий">",
        "pipeline_id": <ID воронки сделок>,
        "tags": [
          {"name": "Itgrix"},
        ]
      }]
    },
    "created_at": <Дата создания неразобранного (в формате Unix Timestamp)>,
    "metadata": {
      "called_at": <Когда сделан звонок (в формате Unix Timestamp)>,
      "duration": <Длительность звонка в секундах>,
      "from": "<Номер телефона звонившего>",
      "is_call_event_needed": false,
      "link": "<Ссылка на запись звонка>",
      "phone": "<Номер телефона, на который звонили>",
      "service_code": "itgrix_amo",
      "uniq": "<Уникальный идентификатор звонка.
                Itgrix передает linkedid звонка>"
    },
    "pipeline_id": <ID воронки сделок>,
    "source_name": "itgrix_amo",
    "source_uid": "<UID источника заявки.
                    Itgrix передает linkedid звонка>"

    // Прочие поля также можно установить
  },
  "state": "success"
}

Параметры запроса создания неразобранного описаны в документации API amoCRM.