Загрузка звонков и разговоров

Параметр	Значение
Необходимые компоненты для работы с методом	"Data API для настройки", "Загрузка звонков из внешней системы"
Необходимые компоненты для работы с файлами разговоров в формате wav	"Речевая аналитика звонков"
Вес метода	5 балов
Максимальное количество звонков в одном запросе	500 шт
Максимальный размер JSON	512 Кб
IP адрес сервера, которому необходимо дать доступ для загрузки файлов	195.211.122.249

Метод	`upload.calls`
Описание	Загрузка звонков и разговоров для речевой или сквозной аналитики
Кому доступен	Агент, Клиент

Параметры запроса

Название	Тип	Обязательный	Допустимые значения	Описание
`access_token`	string	да		Ключ сессии аутентификации
`user_id`	number	нет		Уникальный идентификатор пользователя клиента агента от имени которого делается запрос Является обязательным для агента Для получения списка пользователей клиента необходимо использовать метод "get.customer_users"
`calls`	array	да		Список звонков. Максимально 500
`ext_id`	string	да		Уникальный идентификатор звонка в вашей системе. Если в системе уже есть успешно загруженный звонок или уже есть 3 попытки ошибочной загрузки звонка с данным ext_id, то данный звонок будет игнорирован.
`direction`	enum	нет	in - входящий звонок out - исходящий звонок	Направление звонка Значение по умолчанию 'in'
`calling_phone_number`	string	да	E164. Если `direction = in` может быть ""	Номер звонящего
`called_phone_number`	string	да	E164. Если `direction = out` может быть ""	Номер куда звонили
`start_time`	iso8601	да	YYYY-MM-DD hh:mm:ss	Дата и время начала сессии звонка
`finish_time`	iso8601	да	YYYY-MM-DD hh:mm:ss	Время окончания сессии звонка. Не может быть меньше чем `start_time`
`is_lost`	boolean	да		Признак, что звонок потерянный или успешный
`is_transfer`	boolean	нет		Значение по умолчанию `false`. Признак, был ли трансфер в сессии звонка Порядок разговора сотрудников определяется в параметрах wav_records и mp3_records
`wait_duration`	number	нет		Длительность ожидания абонента до первого разговора с сотрудником. Значение в секундах.
`talk_duration`	number	нет		Длительность разговора - от момента первого разговора абонента с сотрудником до окончания разговора с последним сотрудником. Значение в секундах
`visitor_session_id`	number	нет		Уникальный идентификатор сессии посетителя полученной из CoMagic. Параметр нужен, если требуется аналитика рекламных кампаний.
`campaign_id`	number	нет		Уникальный идентификатор рекламной кампании в CoMagic. Параметр игнорируется, если заполнен visitor_session_id
`source_id`	number	нет		Уникальный идентификатор источника. Возможно передать только неудаленный источник в разрезе клиента. Если передан `visitor_session_id`, то определим `source_id` по параметрам сессии.
`site_id`	number	нет		Уникальный идентификатор сайта в CoMagic Параметр игнорируется, если заполнен `visitor_session_id` или `called_phone_number` принадлежит другому сайту.
`comment`	string	нет		Комментарий к звонку. Можно указывать название сервиса или формы, которые сгенерировали звонок.
Уведомление об обработке звонка
`callback`	object	нет		Уведомление об обработке звонка Формат уведомления JSON
`url`	string	да		http/https адрес на которые будет отправлено уведомление об успешной обработке звонка.
`events`	array	да	`processed` - переданный звонок обработан успешно `in_process` - звонок в процессе обработки `error` - ошибка обработки звонка	Какие уведомления об обработке звонка получать
Теги звонка
`tags`	array	нет		Теги звонка
`tag_id`	number	нет		Уникальный идентификатор тега в системе CoMagic
`tag_name`	string	да		Название тега. Ищем по названию тег в нашей системе, если не нашли, то создаем и ставим его на звонок. Если нашли, то ставим найденный тег на звонок. Поиск чувствительный к регистру. Для простановки тега "Продажа" необходимо использовать метод "set.tag_sales"Игнорируется, если заполнен `tag_id`
Файлы разговора для речевой аналитики
`wav_records`	array	нет		Файлы разговора для речевой аналитики Возможно передать только если подключен компонент "Речевая аналитика звонков". Из wav-файлов автоматически создаются mp3-записи для прослушивания в личном кабинете
`employee_id`	number	нет		Уникальный идентификатор сотрудника в системе CoMagic
`employee_name`	string	да		Название сотрудника (ФИО) Ищем сотрудника по названию (ФИО) в нашей системе, если не нашли, то создаем и связываем его со звонком. Если нашли, то связываем его со звонком. Поиск не чувствительный к регистру. Игнорируется, если заполнен `employee_id`
`employee_channel`	enum	да	left - левый канал right - правый канал	Указывает в каком канале находится сотрудник Значения только left или right
`record_url`	string	да		Адрес по которому можно скачать файл разговора. Ожидаем только https.
Файлы разговора для прослушивания в личном кабинете
`mp3_records`	array	нет		Файлы разговора для прослушивания в личном кабинете. Запрещено передавать, если заполнен параметр wav_records
`employee_name`	string	нет		Название сотрудника (ФИО) Ищем сотрудника по названию (ФИО) в нашей системе, если не нашли, то создаем и связываем его со звонком. Если нашли, то связываем его со звонком. Поиск не чувствительный к регистру. Игнорируется, если заполнен `employee_id`
`employee_id`	number	нет		Уникальный идентификатор сотрудника в системе CoMagic
`record_url`	string	да		Адрес по которому можно скачать файл разговора

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

Название	Тип	Обязательный	Описание

Параметры уведомления о статусе обработки

Название	Тип	Обязательный	Допустимые значения	Описание
`status`	enum	да	processed - обработано in_process - в процессе обработки error - ошибка обработки	Статус обработки загруженного звонка
`ext_id`	string	да		Уникальный идентификатор звонка в вашей системе
`call_session_id`	number	нет		Уникальный идентификатор сессии звонка в CoMagic (см. метод `get.calls_report`)
`timestamp`	number	да		Время создания события в UTC GMT+00:00
`error_message`	string	нет		Сообщение об ошибке. Заполняется, если параметр status имеет значение "error"
`error_code`	enum	нет		Мнемоника ошибки. Заполняется, если параметр status имеет значение "error"

Требования к wav-файлам для речевой аналитики

Запись звонка в стерео-режиме с двумя аудио-каналами: речь сотрудника в одном канале, речь клиента в другом канале.

ИКМ-16 бит

Частоты дискретизации: 8000 Гц

Частотный диапазон не хуже 330-3400 Гц;

Отношение сигнал/шум в частотном диапазоне 330-3400 Гц: не менее 15 дБ;

Минимальная продолжительность речевого сигнала 16 сек;

Размер файла не больше 50Mb

Требования к сервису, который будет отдавать записи разговоров, при их загрузке по переданному URL

В ответе на запрос для загрузки wav файлов должен быть заголовок Content-Type: audio/wav
В ответ на запрос для загрузки mp3 файлов должен быть заголовок Content-Type: audio/mpeg

JSON структура запроса

{
  "jsonrpc": "2.0",
  "id": "number",
  "method": "upload.calls",
  "params": {
    "access_token": "string",
    "user_id": "number",
    "calls": [
      {
        "callback": {
          "url": "string",
          "events": [

          ]
        },
        "ext_id": "string",
        "direction": "enum",
        "calling_phone_number": "string",
        "called_phone_number": "string",
        "start_time": "iso8601",
        "finish_time": "iso8601",
        "is_lost": "boolean",
        "is_transfer": "boolean",
        "visitor_session_id": "number",
        "site_id": "number",
        "campaign_id": "number",
        "source_id": "number",
        "wait_duration": "number",
        "talk_duration": "number",
        "comment": "string",
        "tags": [
          {
            "tag_id": "number",
            "tag_name": "string"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "enum",
            "employee_name": "string",
            "employee_id": "number",
            "record_url": "string"
          }
        ],
        "mp3_records": [
          {
            "employee_name": "string",
            "employee_id": "number",
            "record_url": "string"
          }
        ]
      }
    ]
  }
}

JSON структура ответа

Ответ приходит как только система сохранила звонки для дальнейшей обработки. По окончанию обработки звонка придет web-hook со со статусом обработки.

{
  "jsonrpc": "2.0",
  "id": "number",
  "result": {
  "data": {
      "success": "true"
    }
  }
}

JSON структура о статусе обработки

{
  "ext_id": "string",
  "call_session_id": "number",
  "status": "enum",
  "timestamp": "number",
  "error_message": "string",
  "error_code": "enum"
}

Пример для речевой аналитики, загрузка звонка абонента с несколькими сотрудниками одним wav-файлом

Клиент загружает звонок в котором был трансфер и разговор абонент с несколькими сотрудниками.

{
  "jsonrpc": "2.0",
  "id": "number",
  "method": "upload.calls",
  "params": {
    "access_token": "string",
    "calls": [
      {
        "ext_id": "test1",
        "direction": "in",
        "calling_phone_number": "89262444397",
        "called_phone_number": "84955140576",
        "start_time": "2019-07-01 12:00:00",
        "finish_time": "2019-07-01 12:00:30",
        "is_lost": false,
        "is_transfer": true,
        "wait_duration": 10,
        "talk_duration": 20,
        "tags": [
          {
            "tag_name": "Целевой"
          },
          {
            "tag_name": "Тест"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "left",
            "employee_name": "Иван Васильевич",
            "record_url": "https://test.ru/shhgad-adjjsdf-ytrh"
          },
          {
            "employee_channel": "right",
            "employee_name": "Александр Васильевич",
            "record_url": "https://test.ru/shhgad-adjjsdf"
          }
        ]
      }
    ]
  }
}

Пример для речевой аналитики, загрузка звонка абонента с сотрудником одним wav-файлом

Клиент загружает звонок, в котором разговаривал абонент с одним сотрудником.

{
  "jsonrpc": "2.0",
  "id": "number",
  "method": "upload.calls",
  "params": {
    "access_token": "string",
    "calls": [
      {
        "ext_id": "test1",
        "direction": "in",
        "calling_phone_number": "89262444397",
        "called_phone_number": "84955140576",
        "start_time": "2019-07-01 12:00:00",
        "finish_time": "2019-07-01 12:00:30",
        "is_lost": false,
        "wait_duration": 10,
        "talk_duration": 20,
        "tags": [
          {
            "tag_name": "Целевой"
          },
          {
            "tag_name": "Тест"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "left",
            "employee_name": "Иван Васильевич",
            "record_url": "https://test.ru/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

Пример для сквозной аналитики, загрузка звонков от стороннего коллтрекинга

{
  "jsonrpc": "2.0",
  "id": "number",
  "method": "upload.calls",
  "params": {
    "access_token": "string",
    "calls": [
      {
        "ext_id": "test1",
        "direction": "in",
        "calling_phone_number": "89262444397",
        "called_phone_number": "84955140576",
        "start_time": "2019-07-01 12:00:00",
        "finish_time": "2019-07-01 12:00:30",
        "is_lost": false,
        "campaign_id": 435,
        "source_id": -1,
        "site_id": 24,
        "tags": [
          {
            "tag_name": "Целевой"
          },
          {
            "tag_name": "Тест"
          }
        ],
        "mp3_records": [
          {
            "record_url": "https://test.ru/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

Пример для сквозной аналитики, загрузка звонков от формы обратного звонка

{
  "jsonrpc": "2.0",
  "id": "number",
  "method": "upload.calls",
  "params": {
    "access_token": "string",
    "calls": [
      {
        "ext_id": "test1",
        "direction": "in",
        "calling_phone_number": "89262444397",
        "called_phone_number": "84955140576",
        "start_time": "2019-07-01 12:00:00",
        "finish_time": "2019-07-01 12:00:30",
        "is_lost": false,
        "visitor_session_id": 435,
        "tags": [
          {
            "tag_name": "Целевой"
          },
          {
            "tag_name": "Тест"
          }
        ],
        "mp3_records": [
          {
            "record_url": "https://test.ru/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

Пример уведомления о статусе обработки звонка

{
  "ext_id": "test1",
  "call_session_id": "1564545",
  "status": "processed",
  "timestamp": "1562156217"
}

Список возвращаемых ошибок

Параметр	Значение
max_file_size_download_error	Превышен максимальный размер файла. На текущий момент - 50 Мб.
decode_error	Не смогли открыть файл разговора, отсутствуют первые байты в файлах mp3 - ID3 и wav - RIFF или при процессе декодирования возникла ошибка.
wav_min_duration_processing_error	Скаченный wav-файл короче 16 секунд.
wav_channels_processing_error	Скаченный wav-файл не содержит 2 канала.
wav_processing_error	Ошибка при обработке wav-файла при кодирования файла к нужным параметрам.
connection_download_error	Ошибка при подключении к серверу. Проблема с сетью.
http_status_download_error	Сервер с которого скачиваем файл ответил не 200.
http_content_type_download_error	Content-Type не соответствует спецификации.
timeout_download_error	Очень долго скачивался файл или очень долго происходило соединение с сервером. Максимальное время - 30 секунд

Смотрим раздел "Список ошибок для методов с глаголом create"