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.

  <th>

  </th>
</tr>

  <td>
    <br />The [***recording key***](https://guide.ximasoftware.com/docs/authentication#section-recording-key) for the recording for which the audio file is requested.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />format (optional)\ <br />
  </td>

  <td>
    <br /><hr><br />The audio file type returned. Supported audio types are spx (default) and wav.\ <br />
  </td>
</tr>

Arguments
recording‑key

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.

  <th>

  </th>
</tr>

  <td>
    <br />An invalid \{format} was provided.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />401 Unauthorized
  </td>

  <td>
    <br /><hr><br />The [***authorization header***](https://guide.ximasoftware.com/docs/authentication#section-authentication) wasn’t valid.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />403 Forbidden
  </td>

  <td>
    <br /><hr><br />The authenticated user doesn’t have Chronicall access to the <Glossary>Recording</Glossary>.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />404 Not Found\ <br />
  </td>

  <td>
    <br /><hr><br />An invalid [***recording key***](https://guide.ximasoftware.com/docs/authentication#section-recording-key) was provided.\ <br />
  </td>
</tr>

Potential Errors
400 Bad Request

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

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

  <th>

  </th>
</tr>

  <td>
    <br />The [***call key***](https://guide.ximasoftware.com/docs/authentication#section-call-key) for the call for which the audio file is requested.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />format (optional)\ <br />
  </td>

  <td>
    <br /><hr><br />The audio file type returned. Supported audio types are spx (default) and wav.\ <br />
  </td>
</tr>

Arguments
call‑key

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

  <th>
    Failure
  </th>
</tr>

  <td>
    <br />An invalid format was provided.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />401 Unauthorized
  </td>

  <td>
    <br /><hr><br />The [***authorization header***](https://guide.ximasoftware.com/docs/authentication#section-authentication) wasn’t valid.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />403 Forbidden
  </td>

  <td>
    <br /><hr><br />The authenticated user doesn’t have Chronicall access to the call.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />404 Not Found\ <br />
  </td>

  <td>
    <br /><hr><br />An invalid [***call key***](https://guide.ximasoftware.com/docs/authentication#section-call-key) was provided.\ <br />
  </td>
</tr>

Status Code
400 Bad Request

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.

  <th>

  </th>
</tr>

  <td>
    <br />The [***recording key***](https://guide.ximasoftware.com/docs/authentication#section-recording-key) for a recording.\ <br />
  </td>
</tr>

Arguments
recording‑key

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

  <th>
    Failure
  </th>
</tr>

  <td>
    <br />The [***authorization header***](https://guide.ximasoftware.com/docs/authentication#section-authentication) wasn't valid.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />403 Forbidden
  </td>

  <td>
    <br /><hr><br />The authenticated user doesn't have Chronicall access to the <Glossary>Recording</Glossary>.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />404 Not Found\ <br />
  </td>

  <td>
    <br /><hr><br />An invalid [***recording key***](https://guide.ximasoftware.com/docs/authentication#section-recording-key) was provided.\ <br />
  </td>
</tr>

Status Code
401 Unauthorized

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.

  <th>

  </th>
</tr>

  <td>
    <br />The [***call key***](https://guide.ximasoftware.com/docs/authentication#section-call-key) for the call.\ <br />
  </td>
</tr>

Arguments
call‑key

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

  <th>
    Failure
  </th>
</tr>

  <td>
    <br />The [***authorization header***](https://guide.ximasoftware.com/docs/authentication#section-authentication) wasn't valid.\*\*
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />403 Forbidden
  </td>

  <td>
    <br /><hr><br />The authenticated user doesn't have Chronicall access to the call.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />404 Not Found\ <br />
  </td>

  <td>
    <br /><hr><br />An invalid [***call key***](https://guide.ximasoftware.com/docs/authentication#section-call-key) was provided.\ <br />
  </td>
</tr>

Status Code
401 Unauthorized

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

  <th>

  </th>
</tr>

  <td>
    <br />The start of the time frame in milliseconds since epoch.
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />endTime long\ <br />
  </td>

  <td>
    <br /><hr><br />The end of the time frame in milliseconds since epoch.\ <br />
  </td>
</tr>

Arguments
startTime long

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

  <th>
    Failure
  </th>
</tr>

  <td>
    <br />The [***authorization header***](https://guide.ximasoftware.com/docs/authentication#section-authentication) wasn't valid.\*\*
  </td>
</tr>

<tr>
  <td>
    <br /><hr><br />403 Forbidden\ <br />
  </td>

  <td>
    <br /><hr><br />The authenticated user doesn't have Chronicall access to the call.\ <br />
  </td>
</tr>

Status Code
401 Unauthorized

Updated 1 day ago