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

Звонки представляют возможность добавлять информацию к сделке, покупателю, контакту или компании. События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате. Если у события звонка есть ссылка на файл записи звонка, то в заметку будет добавлен плеер для проигрывания этой записи. Существует два способа добавления звонков. Первый способ - метод 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 пользователя создавшего примечание о звонке
add/upadted_by int id пользователя обновившего примечание о звонке
add/responsible_user_id int id пользователя ответственного за звонок.

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

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

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

  1. {
  2.    add: [
  3.       {
  4.          uniq: 394427aaf821879e29efbc4eb98er22171514,
  5.          phone_number: "71964444444",
  6.          source => "amo_custom_widget",
  7.          created_at: 1414654739,
  8.          created_by: "999999"
  9.          duration => 98,
  10.          call_status => 2,
  11.          call_result => "Перезвонить позже"
  12.          direction => "inbound",
  13.          link => "http:///* ссылка на запись */.mp3",
  14.          responsible_user_id: "956757",
  15.       },
  16.       {
  17.          uniq: 394427aaf821879e29efbc4eb98er22171514,
  18.          phone_number: "71967777777",
  19.          source => "amo_custom_widget",
  20.          created_at: 1414654739,
  21.          created_by: "999999"
  22.          duration => 44,
  23.          call_status => 4,
  24.          call_result => "Поговорили"
  25.          direction => "inbound",
  26.          link => "http:///* ссылка на запись */.mp3",
  27.          responsible_user_id: "956757",
  28.       },
  29.       {
  30.          uniq: 394427aaf821879e29efbc4eb456t22171514,
  31.          phone_number: "71961111111",
  32.          source => "amo_custom_widget",
  33.          created_at: 1414654739,
  34.          created_by: "999999"
  35.          duration => 120,
  36.          call_status => 4,
  37.          call_result => "Поговорили"
  38.          direction => "inbound",
  39.          link => "http:///* ссылка на запись */.mp3",
  40.          responsible_user_id: "956757",
  41.        }
  42.    ]
  43. }

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

Параметр Описание
_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 Массив содержащий информацию прилегающую к запросу

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

  1. {
  2.    _embedded: {
  3.      items: [
  4.           {
  5.              id: 9854612,
  6.              element_id: 123151112
  7.              element_type: 1
  8.              phone_number: "71964444444",
  9.              _links: {
  10.                  self: "/api/v2/notes?id=9854612&type=contact",
  11.                  method: "get"  
  12.              },
  13.           },
  14.          {
  15.              id: 9854613,
  16.              element_id: 123151112
  17.              element_type: 2
  18.              phone_number: "71967777777",
  19.              _links: {
  20.                  self: "/api/v2/notes?id=9854613&type=lead",
  21.                  method: "get"  
  22.          },
  23.       }
  24.     ],
  25.     errors: [
  26.          {
  27.             msg: "Entity not found",
  28.             code: 263,
  29.             item: {
  30.                  uniq: 394427aaf821879e29efbc4eb456t22171514,
  31.                  phone_number: "71961111111",
  32.                  source => "amo_custom_widget",
  33.                  created_at: 1414654739,
  34.                  created_by: "999999"
  35.                  duration => 120,
  36.                  call_status => 4,
  37.                  call_result => "Поговорили"
  38.                  direction => "inbound",
  39.                  link => "http:///* ссылка на запись */.mp3",
  40.                  responsible_user_id: "956757",
  41.             }
  42.          }
  43.     ]
  44.    }
  45.    _links: {
  46.        self: "/api/v2/calls",
  47.        method: "post"
  48.    }  
  49. }

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

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

  1. $calls['add'] = array(
  2.     0 => array (
  3.         'uniq' => '394427aaf821879e29efbc4eb98ef13271514',
  4.         'phone_number' => '71964444444',
  5.         'source' => 'amo_custom_widget',
  6.         'created_at' => 1414654739,
  7.         'created_by' => '999999'
  8.         'duration' => 98,
  9.         'call_status' => 2,
  10.         'call_result' => 'Перезвонить позже'
  11.         'direction' => 'inbound',
  12.         'link' => 'http:///* ссылка на запись */.mp3',
  13.         'responsible_user_id' => 956757
  14.     ),
  15.     1 => array (
  16.         'uniq' => '394427aaf821879e29efbc4eb98er22171514',
  17.         'phone_number' => '71967777777',
  18.         'source' => 'amo_custom_widget',
  19.         'created_at' => 1414654739,
  20.         'created_by' => '999999'
  21.         'duration' => 44,
  22.         'call_status' => 4,
  23.         'call_result' => 'Поговорили'
  24.         'direction' => 'inbound',
  25.         'link' => 'http:///* ссылка на запись */.mp3',
  26.         'responsible_user_id' => 956757
  27.     ),
  28. );
  29. $code = 'my_service_name'; # Код вашего сервиса в amoCRM
  30. $key = '601eb8fab9707d8009dba552f2d411a3'; # Ключ, полученный в техподдержке
  31. $account_id = 39099; # Идентификационный номер аккаунта, в который добавляются звонки
  32. #Формируем ссылку для запроса
  33. $link='https://субдомен.amocrm.ru/api/v2/calls';
  34. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  35. #Устанавливаем необходимые опции для сеанса cURL
  36. curl_setopt($curl,CURLOPT_POST,TRUE);
  37. curl_setopt($curl,CURLOPT_RETURNTRANSFER,TRUE);
  38. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  39. curl_setopt($curl,CURLOPT_HEADER,FALSE);
  40. curl_setopt($curl,CURLOPT_TIMEOUT,30);
  41. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  42. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  43. curl_setopt($curl,CURLOPT_URL,$link);
  44. curl_setopt($curl,CURLOPT_POSTFIELDS,http_build_query($calls));
  45. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  46.  
  47. /*
  48.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  49.  нам придётся перевести ответ в формат, понятный PHP
  50.  */
  51. $response=json_decode($out,TRUE);
  52. if( count($response['_embedded']['items']) > 0 ) {
  53.     $output .= 'Успешно добавленные звонки:' . PHP_EOL;
  54.     foreach($response['_embedded']['items'] as $v) {
  55.         $output .= $v . PHP_EOL;
  56.     }
  57. }
  58. if( count($response['_embedded']['errors']) > 0 ) {
  59.     $output .= 'Звонки не добавлены:' . PHP_EOL;
  60.     foreach($response['_embedded']['errors'] as $v) {
  61.         $output .= $v . PHP_EOL;
  62.     }
  63. }

Метод 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 Ссылка на файл с записью разговора.

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

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

  1. $calls['request']['add'] = array(
  2.     0 => array (
  3.         'uuid' => '394427aaf821879e29efbc4eb98ef13271514',
  4.         'caller' => 117,
  5.         'to' => '71969681126',
  6.         'date' => 1414654739,
  7.         'billsec' => 98,
  8.         'type' => 'inbound',
  9.     'link' => 'http:///* ссылка на запись */.mp3',
  10.         'account_id'=>1111111
  11.     ),
  12.     1 => array (
  13.         'uuid' => 'b7095fb33b368c7103626d3943d9e61c14697',
  14.         'caller' => 280,
  15.         'to' => '75809543710',
  16.         'date' => 1414653676,
  17.         'billsec' => 57,
  18.         'type' => 'outbound',
  19.         'link' => 'http:///* ссылка на запись */.mp3',
  20.         'account_id'=>1111111
  21.     ),
  22. );
  23. $code = 'my_service_name'; # Код вашего сервиса в amoCRM
  24. $key = '601eb8fab9707d8009dba552f2d411a3'; # Ключ, полученный в техподдержке
  25. $account_id = 39099; # Идентификационный номер аккаунта, в который добавляются звонки
  26. #Формируем ссылку для запроса
  27. $link='https://sip.amocrm.ru/api/calls/add/?code=' . $code . '&key=' . $key . '&account_id=' . $account_id;
  28. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  29. #Устанавливаем необходимые опции для сеанса cURL
  30. curl_setopt($curl,CURLOPT_POST,TRUE);
  31. curl_setopt($curl,CURLOPT_RETURNTRANSFER,TRUE);
  32. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  33. curl_setopt($curl,CURLOPT_HEADER,FALSE);
  34. curl_setopt($curl,CURLOPT_TIMEOUT,30);
  35. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  36. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  37. curl_setopt($curl,CURLOPT_URL,$link);
  38. curl_setopt($curl,CURLOPT_POSTFIELDS,http_build_query($calls));
  39. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  40. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE);
  41. $code=(int)$code;
  42. $errors=array(
  43.     301=>'Moved permanently',
  44.     400=>'Bad request',
  45.     401=>'Unauthorized',
  46.     403=>'Forbidden',
  47.     404=>'Not found',
  48.     500=>'Internal server error',
  49.     502=>'Bad gateway',
  50.     503=>'Service unavailable'
  51. );
  52. try
  53. {
  54.     #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  55.    if($code!=200 && $code!=204)
  56.         throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',(int)$code);
  57. }
  58. catch(Exception $E)
  59. {
  60.     die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  61. }
  62. /*
  63.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  64.  нам придётся перевести ответ в формат, понятный PHP
  65.  */
  66. $response=json_decode($out,TRUE);
  67. if( count($response['response']['calls']['add']['success']) > 0 ) {
  68.     $output .= 'Успешно добавленные звонки:' . PHP_EOL;
  69.     foreach($response['response']['calls']['add']['success'] as $v) {
  70.         $output .= $v . PHP_EOL;
  71.     }
  72. }
  73.  if( count($response['response']['calls']['add']['errors']) > 0 ) {
  74. $output .= 'Ошибки:' . PHP_EOL;
  75. foreach($response['response']['calls']['add']['errors'] as $uuid => $reasons) {
  76.     $output .= $uuid . ' - ' . implode(', ', $reasons) . PHP_EOL;
  77. }
  78. }