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

Звонки представляют возможность добавлять информацию к сделке, покупателю, контакту или компании. События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате. Если у события звонка есть ссылка на файл записи звонка, то в заметку будет добавлен плеер для проигрывания этой записи. Существует два способа добавления звонков. Первый способ - метод 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. #Формируем ссылку для запроса
  30. $link = 'https://субдомен.amocrm.ru/api/v2/calls' ;
  31. $curl = curl_init ( ) ; #Сохраняем дескриптор сеанса cURL
  32. #Устанавливаем необходимые опции для сеанса cURL
  33. curl_setopt ( $curl ,CURLOPT_POST, TRUE ) ;
  34. curl_setopt ( $curl ,CURLOPT_RETURNTRANSFER, TRUE ) ;
  35. curl_setopt ( $curl ,CURLOPT_USERAGENT, 'amoCRM-API-client/1.0' ) ;
  36. curl_setopt ( $curl ,CURLOPT_HEADER, FALSE ) ;
  37. curl_setopt ( $curl ,CURLOPT_TIMEOUT, 30 ) ;
  38. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYPEER, 0 ) ;
  39. curl_setopt ( $curl ,CURLOPT_SSL_VERIFYHOST, 0 ) ;
  40. curl_setopt ( $curl ,CURLOPT_URL, $link ) ;
  41. curl_setopt ( $curl ,CURLOPT_POSTFIELDS, http_build_query ( $calls ) ) ;
  42. $out = curl_exec ( $curl ) ; #Инициируем запрос к API и сохраняем ответ в переменную
  43.  
  44. /*
  45.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  46.  нам придётся перевести ответ в формат, понятный PHP
  47.  */
  48. $response = json_decode ( $out , TRUE ) ;
  49. if ( count ( $response [ '_embedded' ] [ 'items' ] ) > 0 ) {
  50.     $output .= 'Успешно добавленные звонки:' . PHP_EOL;
  51.     foreach ( $response [ '_embedded' ] [ 'items' ] as $v ) {
  52.         $output .= $v . PHP_EOL;
  53.     }
  54. }
  55. if ( count ( $response [ '_embedded' ] [ 'errors' ] ) > 0 ) {
  56.     $output .= 'Звонки не добавлены:' . PHP_EOL;
  57.     foreach ( $response [ '_embedded' ] [ 'errors' ] as $v ) {
  58.         $output .= $v . PHP_EOL;
  59.     }
  60. }

Метод 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. }