Recording Data

After creating a Service User within the Chronicall UI, you will be given an authentication key.
Anytime a request is made to the API, an authentication key must be present.

Add the following header to your API request:

 Authorization : Bearer {authentication_key}

By having the authorization key present, you will be able to access everything that the Service User is set up in Chronicall to have access to.

Note: For this feature, you must be updated to version 4.0.9 or newer.

Use Cases

  • Programmatically download audio files to be imported into another system
  • Programmatically generate links to play recorded calls outside of Chronicall
  • To see an example, click here.

Obtaining Audio Files

GET /rest/api/v1/recordings/{recording-key}/audio?format={format}

An endpoint to download a single Recording.

Arguments

recording‑key

The recording key for the recording for which the audio file is requested.



format (optional)




The audio file type returned. Supported audio types are spx (default) and wav.

Response

If a successful request is made, then the response will be a file containing the audio of the Recording in the specified file type.

Potential Errors

400 Bad Request

An invalid {format} was provided.



401 Unauthorized



The authorization header wasn’t valid.



403 Forbidden



The authenticated user doesn’t have Chronicall access to the Recording.



404 Not Found




An invalid recording key was provided.

GET /rest/api/v1/calls/{call-key}/audio?format={format}

An endpoint to download all of the Recordings on a call.

Arguments

call‑key

The call key for the call for which the audio file is requested.



format (optional)




The audio file type returned. Supported audio types are spx (default) and wav.

Response

If a successful request is made, then the response will be a file containing the audio of the call’s Recordings in the specified file type.

Potential Errors

Status CodeFailure

400 Bad Request

An invalid format was provided.



401 Unauthorized



The authorization header wasn’t valid.



403 Forbidden



The authenticated user doesn’t have Chronicall access to the call.



404 Not Found




An invalid call key was provided.

Exporting Audio Files

POST /rest/api/v1/recordings/audio?format={format}

An endpoint to download all authorized recordings in a timeframe or a specified list of recordings, in the specified format spx (default) or wav. This requires a JSON request body.

Arguments

format (optional)


The audio file type returned. Supported audio types are spx (default) and wav.

{ 
      "startTime":"{startTime}",
      "endTime":"{endTime}"
     }
{ 
       "recordingKeys":[
         "{uuid}-{start}",
         "{uuid}-{start}",
         "{uuid}-{start}"
       ]
     }

Response

If a successful request is made, then the response will be a Zip File containing the audio of the recordings requested in the specified file type with a file containing details on each recording.

Potential Errors

Status CodeFailure

400 Bad Request

An invalid {format} or malformed JSON request body.



401 Unauthorized



The authorization header wasn't valid.



403 Forbidden




The authenticated user doesn't have Chronicall access to the Recording.

POST /rest/api/v1/calls/audio?format={format}

An endpoint to download all authorized recordings from calls in a timeframe or a specified list of calls, in the specified format spx (default) or wav. This requires a JSON request body.

{ 
      "startTime":"{startTime}",
      "endTime":"{endTime}"
     }
{ 
       "callKeys":[
        "{uuid}-{start}-{end}",            
        "{uuid}-{start}-{end}",
        "{uuid}-{start}-{end}"
       ]
}

Response

If a successful request is made, then the response will be a Zip File containing the audio of the calls requested in the specified file type with a file containing details on each recording.

Potential Errors

Status CodeFailure

400 Bad Request

An invalid {format} or malformed JSON request body.



401 Unauthorized



The authorization header wasn't valid.



403 Forbidden




The authenticated user doesn't have Chronicall access to the Recording.

Creating External Listen Links

POST /rest/api/v1/recordings/{recording-key}/external-listen-link

Obtain an External Listen Link for a specific Recording.

This requires that System Settings -> Basic Settings -> Externally Accessible Address in Chronicall be set with protocol (e.g. http://), domain (e.g., mywebsite.com or 10.0.0.101), and port (if applicable, e.g., :9080), for example: http://10.0.0.101:9080.

Arguments

recording‑key


The recording key for a recording.

Response

If a successful request is made then a json result is returned. The External Listen Link that is generated will be valid forever (Integer.MAX_VALUE days).

{ 
   "listenLink":"http://www.my-chronicall.com/extlisten/recording/
   index.html?id\u003dc9ab20e0-9ad7-4eda-90be-cb401c39f981"
}

Potential Errors

Status CodeFailure

401 Unauthorized

The authorization header wasn't valid.



403 Forbidden



The authenticated user doesn't have Chronicall access to the Recording.



404 Not Found




An invalid recording key was provided.

POST /rest/api/v1/calls/{call-key}/external-listen-link

Obtain an External Listen Link for a specific call.

This requires that System Settings -> Basic Settings -> Externally Accessible Address in Chronicall be set with protocol (e.g., http://), domain (e.g., mywebsite.com or 10.0.0.101), and port (if applicable, e.g., :9080), for example: http://10.0.0.101:9080.

Arguments

call‑key


The call key for the call.

Response

If a successful request is made, then a json result is returned. The external listen link that is generated will be valid forever (Integer.MAX_VALUE days).

{ 
   "listenLink":"http://www.my-chronicall.com/extlisten/recording/
   index.html?id\u003dc9ab20e0-9ad7-4eda-90be-cb401c39f981"
}

Potential Errors

Status CodeFailure

401 Unauthorized

The authorization header wasn't valid.**



403 Forbidden



The authenticated user doesn't have Chronicall access to the call.



404 Not Found




An invalid call key was provided.

Obtaining Recording Data

GET /rest/api/v1/calls/{call-key}/recordings

An endpoint to obtain all of the recording records for a given call.

Response

If a successful request is made, then a json list of basic recording record data will be returned.

[ 
   { 
      "recordingKey":"83849370-5753-4186-9fc5-9c069e615734-1568735345298",
      "startTime":1568735345298,
      "duration":48974,
      "poolId":"d25839a1-2916-4825-8a36-299a1119f732",
      "size":42443,
      "eventId":50165,
      "recordingSystemId":1,
      "status":"SAVED"
   },
   { 
      "recordingKey":"0a72f610-8615-4ac9-8f1d-b914f9f164dc-1568739643644",
      "startTime":1568739643644,
      "duration":59347,
      "poolId":"308b6f52-1f61-4c4f-9ee4-543f37f3937f",
      "size":49743,
      "eventId":54035,
      "recordingSystemId":1,
      "status":"SAVED"
   }
]
Arguments

startTime long

The start of the time frame in milliseconds since epoch.



endTime long




The end of the time frame in milliseconds since epoch.

Response

If a successful request is made, then a json list of basic recording record data will be returned. The result can be an empty list. Recordings for which the user does not have access will not be returned.

[ 
   { 
      "recordingKey":"83849370-5753-4186-9fc5-9c069e615734-1568735345298",
      "startTime":1568735345298,
      "duration":48974,
      "poolId":"d25839a1-2916-4825-8a36-299a1119f732",
      "size":42443,
      "eventId":50165,
      "recordingSystemId":1,
      "status":"SAVED"
   },
   { 
      "recordingKey":"0a72f610-8615-4ac9-8f1d-b914f9f164dc-1568739643644",
      "startTime":1568739643644,
      "duration":59347,
      "poolId":"308b6f52-1f61-4c4f-9ee4-543f37f3937f",
      "size":49743,
      "eventId":54035,
      "recordingSystemId":1,
      "status":"SAVED"
   }
]

Potential Errors

Status CodeFailure

401 Unauthorized

The authorization header wasn't valid.**



403 Forbidden




The authenticated user doesn't have Chronicall access to the call.