Uploads calls and call recordings for speech analytics or end-to-end analytics

Method	`upload.calls`
Description	Uploads calls and call recordings for speech analytics or end-to-end analytics
Available to	Agent, Client
Required components	"Data API for Configuration" and "Upload Calls from an External System"
Required component for WAV recordings	"Speech Call Analytics"
Method weight	5 points
Maximum calls per request	50
Maximum JSON size	512 KB
Server IP address to allowlist for file downloads	195.211.122.249

Request parameters

Name	Type	Required	Valid values	Description
`access_token`	string	yes		Access token used to authenticate the request.
`user_id`	number	no		Unique ID of the client user on whose behalf the agent is making the request. Required for agents. To retrieve a list of client users, use the `get.customer_users` method.
`calls`	array	yes		Calls to upload. Maximum: 50.
`ext_id`	string	yes		Unique call ID in your system. The call is ignored if the same ext_id has already been uploaded successfully or if three previous upload attempts for that ext_id have failed.
`direction`	enum	no	in - inbound; out - outbound	Call direction. Default: in.
`calling_phone_number`	string	yes	E.164. May be an empty string for inbound calls.	Caller phone number.
`called_phone_number`	string	yes	E.164. May be an empty string for outbound calls.	Called phone number.
`start_time`	iso8601	yes	YYYY-MM-DD hh:mm:ss	Date and time when the call session started.
`finish_time`	iso8601	yes	YYYY-MM-DD hh:mm:ss	Date and time when the call session ended. Must not be earlier than start_time.
`is_lost`	boolean	yes		Indicates whether the call was lost.
`is_transfer`	boolean	no		Indicates whether the call was transferred. Default: false. For transferred calls, the order of employees is determined by the order of entries in wav_records or mp3_records.
`wait_duration`	number	no		Time, in seconds, from the start of the call until the first employee answers.
`talk_duration`	number	no		Total conversation duration, in seconds, from the first employee connection until the conversation with the last employee ends.
`visitor_session_id`	number	no		CallGear visitor session ID. Specify this parameter to associate the call with advertising attribution data.
`campaign_id`	number	no		CallGear advertising campaign ID. Ignored when visitor_session_id is provided.
`source_id`	number	no		CallGear traffic source ID.
`site_id`	number	no		CallGear site ID. Ignored when visitor_session_id is provided or when called_phone_number belongs to a different site.
`comment`	string	no		Comment associated with the call. For example, the name of the service or form that generated the call.
Call-processing notifications
`callback`	object	no		Callback settings for call-processing status notifications.
`url`	string	yes		HTTP or HTTPS URL to which call-processing notifications are sent.
`events`	array	yes	processed - processing completed; in_process - processing in progress; error - processing failed	Processing events that trigger a notification.
Call tags
`tags`	array	no		Call tags
`tag_id`	number	no		Unique tag identifier in the CallGear system
`tag_name`	string	yes		Tag name. CallGear searches for an exact, case-sensitive match. If no matching tag exists, it creates one and assigns it to the call. Ignored when tag_id is provided. To assign the Sale tag, use `set.tag_sales`.
WAV recordings for speech analytics
`wav_records`	array	no		WAV call recordings for speech analytics. Available only when the Speech Call Analytics component is enabled. CallGear automatically creates MP3 versions for playback in the client account.
`employee_id`	number	no		Unique employee identifier in the CallGear system
`employee_name`	string	yes		Employee full name. CallGear performs a case-insensitive search by full name. If no matching employee exists, it creates one and associates it with the call. Ignored when employee_id is provided.
`employee_channel`	enum	yes	left - left channel; right - right channel	Audio channel containing the employee's speech.
`record_url`	string	yes		HTTPS URL from which CallGear can download the recording.
MP3 recordings for playback
`mp3_records`	array	no		MP3 recordings for playback in the client account. Cannot be provided together with wav_records.
`employee_name`	string	no		Employee full name. CallGear performs a case-insensitive search by full name. If no matching employee exists, it creates one and associates it with the call. Ignored when employee_id is provided.
`employee_id`	number	no		Unique employee identifier in the CallGear system
`record_url`	string	yes		URL from which CallGear can download the recording.

Response parameters

The response is returned as soon as the calls have been queued for processing. After processing, CallGear sends a webhook containing the processing status. See "Processing status notifications" below.

Processing status notifications

Name	Type	Required	Valid values	Description
`status`	enum	yes	processed - processing completed; in_process - processing in progress; error - processing failed	Processing status of the uploaded call.
`ext_id`	string	yes		Unique call ID in your system.
`call_session_id`	number	no		CallGear call session ID. See `get.calls_report`.
`timestamp`	number	yes		Unix timestamp for the event, in UTC.
`error_message`	string	no		Error message. Returned when status is error.
`error_code`	enum	no		Error mnemonic. Returned when status is error.

WAV file requirements for speech analytics

Record calls in stereo, with the employee on one audio channel and the customer on the other.
16-bit PCM.
Sample rate: 8,000 Hz.
Frequency response: at least 330-3,400 Hz.
Signal-to-noise ratio across 330-3,400 Hz: at least 15 dB.
Minimum speech duration: 16 seconds.
Maximum file size: 50 MB.

Requirements for the recording download endpoint

WAV downloads must return the Content-Type: audio/wav header.
MP3 downloads must return the Content-Type: audio/mpeg header.

Example request

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

Example response

The response is returned as soon as the calls have been queued for processing. After processing, CallGear sends a webhook containing the processing status.

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

Processing status notification format

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

Speech analytics example: uploading a transferred call with multiple employees

This example uploads a transferred call in which the customer spoke with multiple 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": "Qualified"
          },
          {
            "tag_name": "Test"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "left",
            "employee_name": "John Smith",
            "record_url": "https://test.ae/shhgad-adjjsdf-ytrh"
          },
          {
            "employee_channel": "right",
            "employee_name": "Alex Johnson",
            "record_url": "https://test.ae/shhgad-adjjsdf"
          }
        ]
      }
    ]
  }
}

Speech analytics example: uploading a call with one employee

This example uploads a call in which the customer spoke with one 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": "Qualified"
          },
          {
            "tag_name": "Test"
          }
        ],
        "wav_records": [
          {
            "employee_channel": "left",
            "employee_name": "John Smith",
            "record_url": "https://test.ae/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

End-to-end analytics example: uploading calls from a third-party call-tracking platform

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

End-to-end analytics example: 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": "Qualified"
          },
          {
            "tag_name": "Test"
          }
        ],
        "mp3_records": [
          {
            "record_url": "https://test.ae/shhgad-adjjsdf-xxxx"
          }
        ]
      }
    ]
  }
}

Call-processing status notification example

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

Possible errors

Error mnemonics	Description
`max_file_size_download_error`	The file exceeds the maximum size of 50 MB.
`decode_error`	The recording could not be opened. The file may be missing the expected MP3 ID3 header or WAV RIFF header, or decoding may have failed.
`wav_min_duration_processing_error`	The uploaded WAV file is shorter than 16 seconds.
`wav_channels_processing_error`	The uploaded WAV file does not contain two audio channels.
`wav_processing_error`	The WAV file could not be converted to the required audio format.
`connection_download_error`	CallGear could not connect to the download server because of a network error.
`http_status_download_error`	The download server returned an HTTP status other than 200.
`http_content_type_download_error`	The returned Content-Type header is not supported.
`timeout_download_error`	The connection or download timed out. The maximum allowed time is 30 seconds.

See the "Errors for create methods" section.