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

Звонки представляют возможность добавлять информацию к сделке, покупателю, контакту или компании. События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате. Если у события звонка есть ссылка на файл записи звонка, то в заметку будет добавлен плеер для проигрывания этой записи. Существует два способа добавления звонков. Первый способ - метод 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
),
);
$code = 'my_service_name'; # Код вашего сервиса в amoCRM
$key = '601eb8fab9707d8009dba552f2d411a3'; # Ключ, полученный в техподдержке
$account_id = 39099; # Идентификационный номер аккаунта, в который добавляются звонки
#Формируем ссылку для запроса
$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;
}
}