Логирование звонков

Звонки представляют возможность добавлять информацию к сделке, покупателю, контакту или компании. События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате. Если у события звонка есть ссылка на файл записи звонка, то в заметку будет добавлен плеер для проигрывания этой записи. Существует два способа добавления звонков. Первый способ – метод POST /api/v2/calls, позволяющий мгновенно добавить примечание о звонке в уже существующую карточку с таким номером телефона. Если карточка с номером не была найдена, то звонок добавлен не будет. Второй способ – это добавление звонка с помощью метода calls/add. При использовании этого метода записи звонков попадают в очередь на обработку. Затем, если нашелся контакт/ компания с указанным в параметрах номером, создается примечание типа «Звонок» в карточке. Если контакт/компания не была найдена в течении 18 часов, то звонок удаляется.

Важно знать!

Что при использовании методов логирования, система автоматически находит контакт или компанию с указанным номером телефона, а также все связанные сущнонсти и добавляет звонок в одну из них по следующему алгоритму:

  • если у контакта/компании есть одна активная сделка, и нет связанных покупателей то звонок будет добавлен в сделку
  • если у контакта/компании есть один покупатель и нет активных сделок, то звонок будет добавлен в покупателя
  • в случае если у контакта/компании более одной активной сделки/покупателя или связанные сущности отсутствуют, то звонок будет добавлен в карточку контакта/компании

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

Метод /api/v2/calls

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

URL метода

POST /api/v2/calls/

Параметры

Параметр Тип Описание
add array Список добавляемых звонков
add/phone_number
require
string Внешний номер телефона
add/direction
require
string Тип звонка (inbound – входящий, outbound – исходящий)
add/uniq string Уникальный код звонка
add/duration string Продолжительность звонка в секундах
add/source string Код виджета или сервиса, через который был совершён звонок
add/call_status int Статус звонка. Подробное описание статусов здесь
add/call_result string Результат звонка
add/link string Ссылка на запись звонка
add/created_at timestamp Дата и время создания примечания о звонке
add/updated_at timestamp Дата и время изменения примечания о звонке
add/created_by int id пользователя создавшего примечание о звонке, если в запросе не указан явно, то по умолчанию проставляется id администратора аккаунта. Данный параметр отвечает за отображение имени пользователя в блоках от кого/кому был совершен звонок
add/updated_by int id пользователя обновившего примечание о звонке
add/responsible_user_id int id пользователя ответственного за звонок, при указании этого параметра, ответственный пользователь сможет совершить действие с примечанием (например, удаление)

Статусы звонка

Тип Описание
1 Оставил голосовое сообщение
2 Перезвонить позже
3 Нет на месте
4 Разговор состоялся
5 Неверный номер
6 Не дозвонился
7 Номер занят

Пример запроса

{
  add: [
    {
      uniq: "394427aaf821879e29efbc4eb98er22171514",
      phone_number: "71964444444",
      source: "amo_custom_widget",
      created_at: 1414654739,
      created_by: "999999",
      duration: 98,
      call_status: 2,
      call_result: "Перезвонить позже",
      direction: "inbound",
      link: "http:///* ссылка на запись */.mp3",
      responsible_user_id: "956757",
    },
    {
      uniq: "394427aaf821879e29efbc4eb98er22171514",
      phone_number: "71967777777",
      source: "amo_custom_widget",
      created_at: 1414654739,
      created_by: "999999",
      duration: 44,
      call_status: 4,
      call_result: "Поговорили",
      direction: "inbound",
      link: "http:///* ссылка на запись */.mp3",
      responsible_user_id: "956757",
    },
    {
      uniq: "394427aaf821879e29efbc4eb456t22171514",
      phone_number: "71961111111",
      source: "amo_custom_widget",
      created_at: 1414654739,
      created_by: "999999",
      duration: 120,
      call_status: 4,
      call_result: "Поговорили",
      direction: "inbound",
      link: "http:///* ссылка на запись */.mp3",
      responsible_user_id: "956757",
    }
  ]
}

Параметры ответа

Параметр Описание
_embedded/items/ Массив с успешно добавленными звонками
_embedded/items/id Уникальный идентификатор примичания о звонке
_embedded/items/element_id Уникальный идентификатор сущности, к которой был прикреплен звонок
_embedded/items/element_type Тип сущности, к которой был прикреплен звонок
_embedded/items/phone_number Номер телефона по которому была найдена сущность
_embedded/errors/ Массив со звонками, которые не удалось добавить
_embedded/errors/msg Сообщение об ошибке
_embedded/errors/code Код ошибки. Более подробную информацию об ошибках можно посмотреть тут
_embedded/errors/item Параметры передаваемые для добавления звонка
_links Массив содержащий информацию о запросе
_links/self Массив содержащий информацию о текущем запросе
_links/self/href Относительный URL текущего запроса
_links/self/method Метод текущего запроса
_embedded Массив содержащий информацию прилегающую к запросу

Пример ответа

{
  _embedded: {
    items: [
      {
        id: 9854612,
        element_id: 123151112,
        element_type: 1,
        phone_number: "71964444444",
        _links: {
          self: "/api/v2/notes?id=9854612&type=contact",
          method: "get"
        },
      },
      {
        id: 9854613,
        element_id: 123151112,
        element_type: 2,
        phone_number: "71967777777",
        _links: {
          self: "/api/v2/notes?id=9854613&type=lead",
          method: "get"
        },
      }
    ],
    errors: [
      {
        msg: "Entity not found",
        code: 263,
        item: {
          uniq: "394427aaf821879e29efbc4eb456t22171514",
          phone_number: "71961111111",
          source: "amo_custom_widget",
          created_at: 1414654739,
          created_by: "999999",
          duration: 120,
          call_status: 4,
          call_result: "Поговорили",
          direction: "inbound",
          link: "http:///* ссылка на запись */.mp3",
          responsible_user_id: "956757",
        }
      }
    ]
  },
  _links: {
    self: "/api/v2/calls",
    method: "post"
  }
}

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

Пример интеграции

$calls ['add'] = array(
    0 => array(
        'uniq' => '394427aaf821879e29efbc4eb98ef13271514',
        'phone_number' => '71964444444',
        'source' => 'amo_custom_widget',
        'created_at' => 1414654739,
        'created_by' => '999999',
        'duration' => 98,
        'call_status' => 2,
        'call_result' => 'Перезвонить позже',
        'direction' => 'inbound',
        'link' => 'http:///* ссылка на запись */.mp3',
        'responsible_user_id' => 956757
    ),
    1 => array(
        'uniq' => '394427aaf821879e29efbc4eb98er22171514',
        'phone_number' => '71967777777',
        'source' => 'amo_custom_widget',
        'created_at' => 1414654739,
        'created_by' => '999999',
        'duration' => 44,
        'call_status' => 4,
        'call_result' => 'Поговорили',
        'direction' => 'inbound',
        'link' => 'http:///* ссылка на запись */.mp3',
        'responsible_user_id' => 956757
    ),
);

#Формируем ссылку для запроса
$link = 'https://субдомен.amocrm.ru/api/v2/calls';
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL

#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_HEADER, FALSE);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($calls));

$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную

# Данные получаем в формате JSON, поэтому, для получения читаемых данных,
# нам придётся перевести ответ в формат, понятный PHP
$response = json_decode($out, TRUE);
if (count($response ['_embedded'] ['items']) > 0) {
    $output .= 'Успешно добавленные звонки:' . PHP_EOL;
    foreach ($response ['_embedded'] ['items'] as $v) {
        $output .= $v . PHP_EOL;
    }
}

if (count($response ['_embedded'] ['errors']) > 0) {
    $output .= 'Звонки не добавлены:' . PHP_EOL;
    foreach ($response ['_embedded'] ['errors'] as $v) {
        $output .= $v . PHP_EOL;
    }
}

Метод calls/add

Метод позволяет по одному или пакетно добавлять новые звонки в очередь на обработку для последующего перемещения в таблицу «События». При добавлении звонков через calls/add записи попадают в очередь на обработку. Затем, если нашелся контакт/компания с указанным в параметрах номером, создается примечание типа «Звонок» в карточке. Если контакт/компания не были найдены в течении 18 часов, то звонок удаляется.

Важно знать, что для добавления звонка через метод call/add необходимо иметь уникальный ключ сервиса. Для получения данного ключа, вам необходимо загрузить в систему свой виджет телефонии(можно тестовый) и обратиться к нам в техподдержку.

Имея уникальный ключ вы сможете добавлять звонки на различные аккаунты amoCRM, при условии что на данных аккаунтах будет подключен ваш виджет и уникальные ключи в подключённых пользователями виджетах будут совпадать с залитой вами версией.

URL метода

POST /api/calls/add/

Параметры GET

Параметр Тип Описание
code
require
string Уникальный идентификатор сервиса.
key
require
string (цифрами) Ключ сервиса, который можно получить написав в техническую поддержку amoCRM.

Параметры

Параметр Тип Описание
account_id
require
string (цифрами) Идентификационный номер аккаунта, в котором произошёл звонок.
uuid
require
string Уникальный идентификатор звонка. Передаётся вами.
caller
require
string (цифрами) Номер звонящего. В случае, если тип звонка – исходящий, считается номером пользователя аккаунта. Список пользователей необходимо хранить в настройках виджета в ключе ‘phones’ в поле типа ‘users’ в формате {user_id: phone}, либо в ключе ‘phones_lp’ в поле типа ‘users_lp’, тогда искомым номером будет значение в ключе login элемента массива ‘phones_lp’
to
require
string (цифрами) Номер, на который идёт звонок. В случае, если тип звонка – входящий, считается номером пользователя аккаунта. Список пользователей необходимо хранить в настройках виджета в ключе ‘phones’ в поле типа ‘users’ в формате {user_id: phone}, либо в ключе ‘phones_lp’ в поле типа ‘users_lp’, тогда искомым номером будет значение в ключе login элемента массива ‘phones_lp’
date
require
timestamp Дата звонка
type
require
string Тип звонка (inbound – входящий, outbound – исходящий)
billsec
require
int Продолжительность звонка в секундах.
link string Ссылка на файл с записью разговора.

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

Пример интеграции

$calls ['request'] ['add'] = array(
    0 => array(
        'uuid' => '394427aaf821879e29efbc4eb98ef13271514',
        'caller' => 117,
        'to' => '71969681126',
        'date' => 1414654739,
        'billsec' => 98,
        'type' => 'inbound',
        'link' => 'http:///* ссылка на запись */.mp3',
        'account_id' => 39099
    ),
    1 => array(
        'uuid' => 'b7095fb33b368c7103626d3943d9e61c14697',
        'caller' => 280,
        'to' => '75809543710',
        'date' => 1414653676,
        'billsec' => 57,
        'type' => 'outbound',
        'link' => 'http:///* ссылка на запись */.mp3',
        'account_id' => 39099
    ),
);

$code = 'my_service_name'; # Код вашего сервиса в amoCRM
$key = '601eb8fab9707d8009dba552f2d411a3'; # Ключ, полученный в техподдержке

#Формируем ссылку для запроса
$link = 'https://sip.amocrm.ru/api/calls/add/?code=' . $code . '&key=' . $key;
$curl = curl_init(); #Сохраняем дескриптор сеанса cURL

#Устанавливаем необходимые опции для сеанса cURL
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_USERAGENT, 'amoCRM-API-client/1.0');
curl_setopt($curl, CURLOPT_HEADER, FALSE);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($curl, CURLOPT_URL, $link);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($calls));

$out = curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$code = (int)$code;
$errors = array(
    301 => 'Moved permanently',
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable'
);

try {
    #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
    if ($code != 200 && $code != 204)
        throw new Exception(isset ($errors [$code]) ? $errors [$code] : 'Undescribed error', (int)$code);
} catch (Exception $E) {
    die ('Ошибка: ' . $E->getMessage() . PHP_EOL . 'Код ошибки: ' . $E->getCode());
}

# Данные получаем в формате JSON, поэтому, для получения читаемых данных,
# нам придётся перевести ответ в формат, понятный PHP
$response = json_decode($out, TRUE);

if (count($response ['response'] ['calls'] ['add'] ['success']) > 0) {
    $output .= 'Успешно добавленные звонки:' . PHP_EOL;
    foreach ($response ['response'] ['calls'] ['add'] ['success'] as $v) {
        $output .= $v . PHP_EOL;
    }
}

if (count($response ['response'] ['calls'] ['add'] ['errors']) > 0) {
    $output .= 'Ошибки:' . PHP_EOL;
    foreach ($response ['response'] ['calls'] ['add'] ['errors'] as $uuid => $reasons) {
        $output .= $uuid . ' - ' . implode(', ', $reasons) . PHP_EOL;
    }
}

Обработчик player_prepare

Если перед подгрузкой звонка вам необходимо добавить дополнительную логику (например, добавить параметры к ссылке на звонок), вы можете воспользоваться методом player_prepare

Пример добавления обработчика


define(['jquery'], function ($) {
  var CustomWidget = function () {
    var self = this, // для доступа к объекту из методов
      system = self.system(), //Данный метод возвращает объект с переменными системы.
      langs = self.langs;  //Объект локализации с данными из файла локализации (папки i18n)

    this.callbacks = {
      settings: function () {},
      init: function () {
        return true;
      },
      bind_actions: function () {
        AMOCRM.player_prepare[self.params.widget_code] = function ($el) { // $el - ссылка на звонок
          var link_to_call = $el.attr('href');
          link_to_call += '?foo_param=Y&bar_param=N'; // добавляем get параметры
          this.play($el, link_to_call);  // проигрываем звонок по ссылке
        };
        return true;
      },
      render: function () {
        return true;
        },
      dpSettings: function () {},
      advancedSettings: function () {},
      destroy: function () {},
      contacts: {
        selected: function () {}
      },
      leads: {
        selected: function () {}
      },
      onSave: function () {}
    };
    return this;
  };
  return CustomWidget;
});