Callgear

Parameter	Meaning
Necessary components for working with the method	"Data API for configuration", "Loading calls from an external system"
Necessary components for working with conversation files in wav format	"Speech call analytics"
Method weight	5 points
Maximum number of calls in one request	50 pcs
Maximum JSON size	512 KB
IP address of the server that needs to be given access to download files	195.211.122.249

Method	`upload.calls`
Description	Loading calls and conversations for speech or end-to-end analytics
Available to	Agent, Client

Request parameters

is filled in is filled is filled

Name	Type	Required	Valid values	Description
`access_token`	string	yes		Authentication session key
`user_id`	number	no		Unique user identifier of the agent client on behalf of which the request is made Required for the agent To obtain a list of client users, you must use the "get.customer_users" method
`calls`	array	yes		Call list. Maximum 50
`ext_id`	string	yes		A unique call identifier in your system. If the system already has a successfully downloaded call or there are already 3 attempts to erroneously download a call with a given ext_id, then this call will be ignored.
`direction`	enum	no	in - incoming call out - outgoing call	Call direction Default value 'in'
`calling_phone_number`	string	yes	E164. If `direction = in` could be ""	Caller number
`called_phone_number`	string	yes	E164. If `direction = out` can be ""	The number you called
`start_time`	iso8601	yes	YYYY-MM-DD hh:mm:ss	Date and time of the start of the call session
`finish_time`	iso8601	yes	YYYY-MM-DD hh:mm:ss	End time of the call session. Cannot be less than `start_time`
`is_lost`	boolean	yes		Sign that the call is lost or successful
`is_transfer`	boolean	no		The default value is `false`. Indicator whether there was a transfer during the call session The conversation order of employees is determined in the parameters wav_records and mp3_records
`wait_duration`	number	no		The length of time a subscriber waits before the first conversation with an employee. Value in seconds.
`talk_duration`	number	no		The duration of the conversation is from the moment of the first conversation between the subscriber and the employee until the end of the conversation with the last employee. Value in seconds
`visitor_session_id`	number	no		Unique identifier of the visitor session received from CallGear. The parameter is needed if analytics of advertising campaigns is required.
`campaign_id`	number	no		A unique identifier for an advertising campaign in CallGear. The parameter is ignored if visitor_session_id is filled
`source_id`	number	no		Unique source identifier. It is possible to transfer only a non-remote source in the context of the client. If `visitor_session_id` is passed, then we will determine `source_id` using the session parameters.
`site_id`	number	no		Unique site identifier in CallGear The parameter is ignored if `visitor_session_id` or `called_phone_number` is filled in belongs to another site.
`comment`	string	no		Comment on the call. You can specify the name of the service or form that generated the call.
Notification about call processing
`callback`	object	no		Notification about call processing JSON notification format
`url`	string	yes		http/https address to which notification of successful call processing will be sent.
`events`	array	yes	`processed` - the transferred call was processed successfully `in_process` - call in progress `error` - call processing error	What notifications to receive about call processing
Call tags
`tags`	array	no		Call tags
`tag_id`	number	no		Unique tag identifier in the CallGear system
`tag_name`	string	yes		Tag name. We look for a tag in our system by name, if we don’t find it, then we create it and set it to ring. If found, then we put the found tag on the call. Search is case sensitive. To place the "Sale" tag, you must use the method "set.tag_sales" Ignored if `tag_id`
Conversation files for speech analytics
`wav_records`	array	no		Conversation files for speech analytics It is possible to transmit only if the “Speech Call Analytics” component is connected. MP3 recordings are automatically created from wav files for listening in your personal account
`employee_id`	number	no		Unique employee identifier in the CallGear system
`employee_name`	string	yes		Employee name (full name) We look for an employee by name (full name) in our system, if not found, then create and associate it with the call. If found, we associate it with the call. The search is not case sensitive. Ignored if `employee_id`
`employee_channel`	enum	yes	left - left channel right - right channel	Indicates which channel the employee is in Values only left or right
`record_url`	string	yes		Address where you can download the conversation file. We expect only https.
Conversation files for listening in your personal account
`mp3_records`	array	no		Conversation files for listening in your personal account. Transmitting is prohibited if the wav_records parameter is filled
`employee_name`	string	no		Employee name (full name) We are looking for an employee by name (full name) in our system, if not found, then create and associate it with the call. If found, we associate it with the call. The search is not case sensitive. Ignored if `employee_id`
`employee_id`	number	no		Unique employee identifier in the CallGear system
`record_url`	string	yes		Address where you can download the conversation file

Response parameters

Name	Type	Required	Description

Processing status notification options

Name	Type	Required	Valid values	Description
`status`	enum	yes	processed - processed in_process - in the process of processing error - processing error	Loaded call processing status
`ext_id`	string	yes		Unique call identifier in your system
`call_session_id`	number	no		Unique identifier for a call session in CallGear (see `get.calls_report` method)
`timestamp`	number	yes		Event creation time in UTC GMT+00:00
`error_message`	string	no		Error message. Filled in if the status parameter is "error"
`error_code`	enum	no		Error mnemonics. Filled in if the status parameter is "error"

Requirements for wav files for speech analytics

Record a call in stereo mode with two audio channels: employee speech in one channel, client speech in another channel.

16 bit PCM

Sampling rates: 8000 Hz

Frequency range no worse than 330-3400 Hz;

Signal-to-noise ratio in the frequency range 330-3400 Hz: no less than 15 dB;

Minimum duration of speech signal 16 seconds;

File size no more than 50Mb

Requirements for the service that will provide call recordings when downloading them from the provided URL

The response to a request to download wav files must contain the Content-Type: audio/wav header
In response to a request to download mp3 files there must be a Content-Type header: audio/mpeg

JSON request structure```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 response structure
<blockquote>The response comes as soon as the system has saved the calls for further processing. When the call is processed, a web-hook will be sent with the processing status.</blockquote>```json
{
  "jsonrpc": "2.0",
  "id": "number",
  "result": {
  "data": {
      "success": "true"
    }
  }
}

JSON structure about processing status```json

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

### Example for speech analytics, loading a call from a subscriber with several employees with one wav file
The client downloads a call in which there was a transfer and a conversation between the subscriber and several employees.```json
{
  "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"
          }
        ]
      }
    ]
  }
}

Example for speech analytics, downloading a call between a subscriber and an employee in one wav file

The client downloads a call in which the subscriber spoke with one employee.```json { "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" } ] } ] } }

### Example for end-to-end analytics, loading calls from third-party call tracking```json
{
  "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"
          }
        ]
      }
    ]
  }
}

Example for end-to-end analytics, loading calls from a call back form```json

{ "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" } ] } ] } }

### Example of a call processing status notification```json
{
  "ext_id": "test1",
  "call_session_id": "1564545",
  "status": "processed",
  "timestamp": "1562156217"
}

List of returned errors

Parameter	Meaning
max_file_size_download_error	The maximum file size has been exceeded. Currently - 50 MB.
decode_error	Could not open the conversation file, the first bytes are missing in the mp3 - ID3 and wav - RIFF files, or an error occurred during the decoding process.
wav_min_duration_processing_error	The downloaded wav file is shorter than 16 seconds.
wav_channels_processing_error	The downloaded wav file does not contain 2 channels.
wav_processing_error	Error when processing wav file when encoding the file to the required parameters.
connection_download_error	Error connecting to the server. Network problem.
http_status_download_error	The server from which we downloaded the file did not respond 200.
http_content_type_download_error	Content-Type is out of specification.
timeout_download_error	It took a very long time to download a file or a very long time to connect to the server. Maximum time - 30 seconds

See the section "List of errors for methods with the create verb"

Request parameters

Response parameters

Processing status notification options

Requirements for wav files for speech analytics

Requirements for the service that will provide call recordings when downloading them from the provided URL

JSON request structure```json

JSON structure about processing status```json

Example for speech analytics, downloading a call between a subscriber and an employee in one wav file

Example for end-to-end analytics, loading calls from a call back form```json

List of returned errors

CallGear online demo

Thank you, we've got your request!

Choose the number of employees who will use telephony

Choose the industry in which your company operates

Choose your CRM

Thanks!

Choose your region for a better connection

Account recovery