https://support.tethr.com/hc/en-us/categories/115001740967-Developers Developers
https://support.tethr.com/hc/en-us/sections/115003048847-APIs APIs
  1. Support
  2. Developers
  3. APIs

Archived Call Upload API

Follow

New feature: content organization, collaboration and filtering

This article describes a new feature that may not be available to all users. If you don't see this feature and want to learn more, please contact your Tethr admin.
Section only

SDK

Authentication

Note: To request a bearer token, reference the Token authentication API article.

Archived Call

Archived calls are uploaded as multipart form data as specified in rfc2388.

Example of uploading WAV file with metadata:

POST https://[INSTANCE NAME].Audio.Tethr.com/callCapture/v1/archive
Expect: 100-continue
Authorization: Bearer  [TOKEN]
Content-Type: multipart/form-data; boundary=------------------------9523f8b393a93f13

--------------------------9523f8b393a93f13
Content-Disposition: form-data; name="info"
Content-Type: application/json

{
	"sessionId" : "Session ID",
	"masterCallId" : "2545684745",
	"audio" : {
		"format" : "wav"
	},
	"startTime" : "2015-06-04T13:26:17Z",
	"endTime" : "2015-06-04T13:48:17Z",
        "direction" : "Inbound",
        "numberDialed" : "5555551234",
	"contacts" : [{
			"type" : "agent",
			"channel" : 0,
			"phoneNumber" : "555-555-1234",
			"referenceId" : "3241",
			"firstName" : "John",
			"lastName" : "Doe"
		}, {
			"type" : "customer",
			"channel" : 1,
			"phoneNumber" : "444-555-9876"
		}
	],
	"metaData" : {
		"callQueue" : "Service-Change",
		"transferredFrom" : {
			"sessionId" : "PriorCalls Session ID",
			"holdTime" : "PM01S04"
		}
	}
}

--------------------------9523f8b393a93f13
Content-Disposition: form-data; name="data"
Content-Type: audio/wav
Content-Transfer-Encoding: BINARY

Unprintable binary WAV Audio Data goes here
--------------------------9523f8b393a93f13--

metaData

The “metaData” object can hold any standard JSON object.

All data will be stored with the call data and can be made accessible in the UI, Reports, or external data feeds to other systems.

An example of a data object that could be placed here:

An external Customer ID from a CRM platform that was located because of data the customer gave to an IVR, or by the Agent and passed along in the SipRec headers.

Note: The metadata in the example does not represent any standard or schema that must be used.

session and callIds

Session IDs must be a unique value per recording.

direction

The direction value must be one of “Inbound”, “Outbound”, “Internal”, or “Unknown”.

numberDialed

If the number dialed is available, put it here. When included, the number dialed will appear on the call display user interface.

masterCallId

The master call ID is used to associate multiple recordings into a single interaction. Recordings with the same MasterCallId are assumed to belong to the same interaction. See Use of Master Call Id below for more details.

Audio formats

Supported audio formats are:

  • wav - A standard WAV file. Codecs allowed are PCM, and uLaw. Content type for that section must be audio/wav.
  • mp3 - An MP3 file. Content type for that section must be audio/mp3.
  • opus - An opus file encapsulated with OGG, as defined by RFC 7845. The content type for that section must be audio/ogg. Contact data The channel field can be zero-base or one-base. If channel zero is not specified, it is assumed to be one-base.

Example Curl command:

curl -X POST -H "Authorization: bearer [TOKEN]" -F "info=@Sample.json;type=application/json" -F "data=@Sample.wav;type=audio/wav" https://[INSTANCE NAME].Audio.Tethr.com/callCapture/v1/archive

Response

The server will respond with a Tethr-Assigned call ID.

Example:

{"callId":"bbsnbcbe3"}

The Call ID uniquely identifies the call as it appears in Tethr. It can be used to create a GUI link to the call.

Example:

https://[INSTANCE NAME].Tethr.com/calls/bbsnbcbe3

This is the primary ID for the call in Tethr, and wherever possible should be stored by the integrating system for troubleshooting purposes.

If necessary the Tethr call ID can be looked up by Session ID using the Call Status API.

Call Status

Calls can be checked for processing status by their Session ID. Multiple SessionID statuses can be queried in a single invocation.

POST https://[INSTANCE NAME].Audio.Tethr.com/callCapture/v1/status HTTP/1.1
Authorization: Bearer [TOKEN]
Content-Type: application/json; charset=utf-8
Content-Length: 60
Expect: 100-continue

{"CallSessionIds":["Session ID"]}

The response:

{
	"callSessions": [{
		"status": "Concluded",
		"callId": "bbsnblthl",
		"sessionId": "Session ID"
	}]
}

To query multiple IDs:

POST https://[INSTANCE NAME].Audio.Tethr.com/callCapture/v1/status HTTP/1.1
Authorization: Bearer [TOKEN]
Content-Type: application/json; charset=utf-8
Content-Length: 80
Expect: 100-continue

{"CallSessionIds":["458789546-5448241","458789546-1554856","458789546-1144587"]}

Multiple results:

{
	"callSessions": [{
		"status": "Complete",
		"callId": "bbsnbltht",
		"sessionId": "458789546-5448241"
	},
	{
		"status": "Complete",
		"callId": "bbsnblth3",
		"sessionId": "458789546-1554856"
	},
	{
		"status": "Complete",
		"callId": "bbsnbltjc",
		"sessionId": "458789546-1144587"
	}]
}

The status can be:

  • InProgress - Applicable only to the live capture interface. The call is still active and Tethr has received notification that the call has started.
  • Concluded - The call has been fully transmitted to Tethr and is still being processed.
  • Complete - The call has been received and processing is complete.
  • NotFound - The call has not been received by Tethr.

Call Result

Once the call is complete, you can request the completed call results using the following curl command.  See Outbound WebHooks for details on the data result. 

Note: Please contact support to enable this on your API user.

curl -k -X GET "https://[INSTANCE NAME].Audio.Tethr.com/Calls/v1/[CallId]" -H "Authorization: bearer [TOKEN]"

Recording Settings

Tethr contains a mechanism to specify which stations or users should be sent to Tethr. It returns an array of lookup ID’s that the sending side can use to filter the calls.

GET https://<INSTANCE NAME>.Audio.Tethr.com/sources/v1/recordingSettings HTTP/1.1 Authorization: Bearer <TOKEN>

Example result:

[{
	"refType": "Agent",
	"source": "Chaz",
	"lookupId": "1001",
	"recordingSetting": "None"
},
{
	"refType": "Agent",
	"source": "Chaz",
	"lookupId": "1002",
	"recordingSetting": "None"
},
{
	"refType": "Agent",
	"source": "Chaz",
	"lookupId": "1003",
	"recordingSetting": "None"
},
{
	"refType": "Agent",
	"source": "Chaz",
	"lookupId": "1004",
	"recordingSetting": "None"
}]

The lookupId corresponds to a user ID. It is most often used to filter the calls by. The recordingSetting variable is either “None” or “Disabled”. If the user ID of an incoming call does not exist in the list, or if the recordingSetting is set to “Disabled”, then it is expected that the call should not be sent to Tethr.

If the software that sends calls to Tethr self-determines which calls to send without the use of Tethr’s settings, use of this feature is optional.

Audio file structure
This API is expecting a single well-formed WAVE file, with one Riff header at the start of the file or single well-formed MP3 or Ogg opus file, that representing the entirety of a call, including silence and/or hold times.

This file should have a channel for each participant on a call.

A few examples of structuring different audio files:

  • A call with an internal participant and an external participant: The file should have the audio from the internal line on one side, and the external line on the other side.
  • A call between two internal lines: each line would be on its own channel
  • A conference call with two internal lines and an external line: ideally each line would have its own channel, meaning the WAVE file would have 3 channels. If this is not doable, then the internal lines should be on one side, and the external lines on the other side.

Use of Master Call Id
If needed, a call could be split into multiple Tethr calls, but each session would need its own unique session id and should share a Master Call Id. This could happen if a call gets put on hold or transferred, and the recorder creates an individual recording based on the internal side of the call.

Example of the use of masterCallId:

  • A customer calls in, after interacting with the IVR the customer is put on hold for a short while before an agent picks up the call.
  • Only when the agent picks up the call, the call recorder starts recording the call.
  • Sometime into the call the agent puts the call on hold, at this time the call recorder ends the recording session and creates an audio file for that part of the call.
  • When the agent returns to the call, the recorder starts a new session and records the call until the agent and customer complete the interaction and the call is hung up.
  • The recorder then creates another audio file for the second part, but because both calls were for the same caller, they share a SIP callId, but have their own sessionId created by the recorder (this could be the SIP Call Id for the agent’s side of the call, for example).

When the above call is uploaded to Tethr, each part should be uploaded as its own “Call” with all the required and available metadata, along with a shared “master Call Id”.

The same thing may also happen when a call is transferred from one agent to another, where the first session is when the customer is talking to the first agent, and the second session is the part of the call where the customer is talking to the second agent.

Note: Splitting calls into sessions adds complexity in analyzing and understanding what’s happening on calls, and should only be used if the underlying recorder is already operating in this manner. Taking extra steps to split a call after the recorder is strongly discouraged. If you are going to be using the Master Call Id, please reach out to Support@Tethr.com so we can help review your specific needs.

Status Heartbeats

Tethr contains a provision to receive status heartbeat messages from a recorder or broker that uses this API to send archived calls.

It is assumed that heartbeat messages will be sent about every 5 minutes to indicate that the software component responsible for sending calls is still running.

Example heartbeat message:

POST https://<INSTANCE NAME>.Audio.Tethr.com/callCapture/v1/monitor
Authorization: Bearer  <TOKEN>
Content-Type: application/json; charset=utf-8
Host: <INSTANCE NAME>.Audio.Tethr.com:443
Content-Length: 85
Expect: 100-continue

{"Status":1,"TimeStamp":"2017-07-25T21:35:15.0496248+00:00","Name":"WIN-R2IH0DVK1Q4"}
  • Status - the current status.
    • Possible values include:
      • 0 - Unknown (The status is unknown or not specified at this time)
      • 1 - Healthy (Everything is working as expected)
      • 10 - Warning (The system is online, but something is out of normal parameters)
      • 20 - Error (The system is online, but there are errors that should be looked at)
      • 30 - Offline (System is in a non-working state)
  • TimeStamp - The current time that the heartbeat is sent, in ISO 8601 format UTC timezone
  • Name - The name of the application instance. The computer name is generally used.

The heartbeat response will be 204 No Content:

HTTP/1.1 204 No Content
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Strict-Transport-Security: max-age=16070400
x-frame-options: DENY
x-xss-protection: 1; mode=block
x-content-type-options: nosniff
Date: Tue, 25 Jul 2017 21:35:18 GMT

If heartbeats are not supported in the particular Tethr environment, the response will be 404 Not Found.

Articles in this section