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

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

Важно знать!

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

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

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

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