Uploading calls and conversations

Parameter	Value
Components necessary to work with the method	"Data API for settings", "Uploading calls from an outside system"
Components required to work with files in the format wav	"Voice analysis of calls"
Weight of the method	5 points
Maximum number of calls per request	500
Maximum JSON size	512 K
IP address of a server, you need to have access to in order to upload files	195.211.120.37

Method	`upload.calls`
Description	Uploading calls and conversations for voice or end-to-end analysis
Who has access	Agent, Customer

Parameters of a request

Title	Type	Required	Valid value	Description
`access_token`	string	yes		Authentication session key
`user_id`	number	no		Unique user ID of a customer or an agent who makes request. Is mandatory for an agent To get a list of customer users you need to use the method "get.customer_users"
`ext_id`	string	yes		Unique ID of a call in your system. Duplicates are dropped out as calls are uploaded into a data base
`direction`	enum	no	in - incoming call out - outgoing call	Direction of a call Default value is 'in'
`calling_phone_number`	string	yes	E164	Caller's phone number
`called_phone_number`	string	yes	E164	A dialed number
`start_time`	iso8601	yes	YYYY-MM-DD hh:mm:ss	Date and time of a call session's start Data will be corrected with consideration of a time zone set in your client area.
`finish_time`	iso8601	yes	YYYY-MM-DD hh:mm:ss	Completion time of a call session. Can't be earlier than `start_time` Data will be corrected with consideration of a time zone set in your client area.
`is_lost`	boolean	yes		Defines whether a call is lost or successful
`is_transfer`	boolean	no		Default value is `false`. Defines whether transfer occured or not Order for employees communications is set in the parameters wav_records and mp3_records
`wait_duration`	number	no		Waiting time for a subscriber before he or she talks to an employee. Value is in seconds.
`talk_duration`	number	no		Conversation time - a time period from the first call of a subsriber to termination of a call with the last employee. Value is in seconds
`visitor_session_id`	number	no		Unique ID of a visitor session from CallGear. The parameter is required if you need to analyze an advertising campaign.
`campaign_id`	number	no		Unique ID of an advertising campaign in CallGear. Parameter should be ignored, if the parameter visitor_session_id is filled in
`site_id`	number	no		Unique website ID in CallGear Parameter should be ignored if the parameter visitor_session_id is filled in or the parameter called_phone_number belongs to another website.
`comment`	string	no		Comment to a call. Can contain name of a service or a form that generated a call.
Notification about call processing
`callback`	object	no		Notification about call processing JSON notification format
`url`	string	yes		http/https address a notification about successful call processing will be sent to.
`events`	array	yes	processed - call is successfully processed in_process - call is in progress error - call processing error	What notifications about call processing you should get
Call tags
`tags`	array	no		Call tags
`tag_id`	number	no		Unique call tag ID in CallGear
`tag_name`	string	yes		Tag name. You can search tags by their name in the system. If you don't find the one you need, you can create it and use it for a call. If you succesfully found it, just use it for a call. Search is case sensitive. To apply the tag "Sales" use the method "set.tag_sales" This should be ignored if the `tag_id` is filled in
Conversation files for voice analysis
`wav_records`	array	no		Conversation files for voice analysis You can transmit them only if the component "Voice analysis of calls" is active. Wav files automatically convert to mp3 records that you can listen to in your client area.
`employee_id`	number	no		Unique ID of an employee in CallGear
`employee_name`	string	yes		Name of an employee (full name) You can search for an employee in the system by his or hers full name. If you don't find them you can create them and connect them to a call. Search is not case sensitive. This should be ignored if `employee_id` is filled in
`employee_channel`	enum	yes	left - left channel right - right channel	Defines which channel an employee use. Values are only left or right
`record_url`	string	yes		Address you can go to to download conversation files. Wait for https only.
You can listen to conversation files in your client area
`mp3_records`	array	no		You can listen to conversation files in your client area. It's forbidden to transmit them if the parameter wav_records is filled in
`employee_name`	string	no		Employee's full name, You can search for an employee in the system by his or hers full name. If you don't find them you can create them and connect them to a call. Search is not case sensitive. This should be ignored if `employee_id` is filled in
`employee_id`	number	no		Employee's unique ID in the CallGear system
`record_url`	string	yes		Address you can go to to download conversation files.

Parameters of a reply

Title	Type	Required	Description

Parameters of a notification about processing status

Title	Type	Required	Valid value	Description
`status`	enum	yes	processed - processed in_process - in process error - processing error	Processing error of an uploaded file
`ext_id`	string	yes		Unique call ID in your system
`call_session_id`	number	no		Unique ID of a call session in CallGear (refer to the method `get.calls_report`)
`timestamp`	number	yes		Time zone for event generation is UTC GMT+00:00
`error_message`	string	no		Error message. Should be filled in, if the parameter status has value "error"
`error_code`	enum	no		Error mnemonics. Should be filled in, if the parameter status has value "error"

Requirements to wav files for voice analysis

Call recording in stereo mode with two audio channels: employee's voice in one of the channels, customer's voice in the other.

PCM-16 bit

Sampling rate: 8000 hz

Frequency range not worse than 330-3400 hz;

Signal-to-noise ratio at frequency range 330-3400 hz: not less than 15 dB;

Minimum duration of a voice signal is 16 seconds;

File size not more than 50Mb

### Requirements to a service, that will distribute conversations recordings when they are uploaded via given URL - Reply to a request for uploading wav files should have title Content-Type: audio/wav - Reply to a request for uploading mp3 files should have title Content-Type: audio/mpeg ### JSON request structure

{
  "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 reply structure

You get a reply as soon as the system saves calls for further processing. As processing is finished, a web-hook with processing status will be ready.

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

### JSON structure about processing status

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

### Example for a voice analysis, uploading a subscriber's call with several employees in one wav-file Customer uploads a call that includes a transfer and conversations with various employees.

{
  "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": "Targer"
          },
          {
            "tag_name": "Test"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "left",
            "employee_name": "Ivan Vasil'yevich",
            "record_url": "https://test.ru/shhgad-adjjsdf-ytrh"
          },
          {
            "employee_channel": "right",
            "employee_name": "Alexander Vasil'yevich",
            "record_url": "https://test.ru/shhgad-adjjsdf"
          }
        ]
      }
    ]
  }
}

### Example for a voice analysis, uploading a subscriber's call with an employee in one wav-file Customer uploads a call that has a conversation between a subscriber and an employee.

{
  "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": "Target"
          },
          {
            "tag_name": "Test"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "left",
            "employee_name": "Ivan Vasil'yevich",
            "record_url": "https://test.ru/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

### Example of end-to-end analysis, uploading calls from an outside call tracking service

{
  "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": "Target"
          },
          {
            "tag_name": "Test"
          }
        ],
        "mp3_records": [
          {
            "record_url": "https://test.ru/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

### Example of end-to-end analysis, uploading calls from a callback form

{
  "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": "Target"
          },
          {
            "tag_name": "Test"
          }
        ],
        "mp3_records": [
          {
            "record_url": "https://test.ru/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

### Example of a notification about call processing status

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

### List of returning errors | Parameter | Value | | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | max_file_size_download_error | Exceeded maximum file size. at the moment - 50 MB. | | decode_error | Could not open a conversation file, don't have first bytes in mp3 - ID3 and wav - RIFF files or an error occurred during the decoding process. | | wav_min_duration_processing_error | Downloaded wav file is shorter than 16 seconds. | | wav_channels_processing_error | Downloaded wav file does not have 2 channels. | | wav_processing_error | Error in wav file processing or in decoding a file with the needed parameters. | | connection_download_error | Error while connecting a server. Bad connection. | | http_status_download_error | Server from which you download a file responded at 200. | | http_content_type_download_error | Content-Type does not comply with the specification. | | timeout_download_error | File has been downloading for too long or connection with server took too much time. Maximum time is 30 seconds | Refer to ["List of errors for methods with the verb create"](../index.md#_changeErrors)