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

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

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

{
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' => 1111111
) ,
1 => array (
'uuid' => 'b7095fb33b368c7103626d3943d9e61c14697' ,
'caller' => 280 ,
'to' => '75809543710' ,
'date' => 1414653676 ,
'billsec' => 57 ,
'type' => 'outbound' ,
'link' => 'http:///* ссылка на запись */.mp3' ,
'account_id' => 1111111
) ,
) ;
$code = 'my_service_name' ; # Код вашего сервиса в amoCRM
$key = '601eb8fab9707d8009dba552f2d411a3' ; # Ключ, полученный в техподдержке
$account_id = 39099 ; # Идентификационный номер аккаунта, в который добавляются звонки
#Формируем ссылку для запроса
$link = 'https://sip.amocrm.ru/api/calls/add/?code=' . $code . '&key=' . $key . '&account_id=' . $account_id ;
$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;
}
}