Skip to content

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

Параметр Значение
Необходимые компоненты для работы с методом "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
    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",
            "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,
            "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"](../index.md#_changeErrors)