This article will provide a basic breakdown of how customers can use Xima's API to request metadata and copies of recordings.

👍

Best Practices

Send GET requests for recordings no more frequently than once every 3 seconds (per tenant)

For the best performance, schedule recording pulls to be done nightly. No less frequently than every 5 days.

Creating a service user for API integration

Create a new service user as instructed in this article: Configuring a Service User

You may name the service user whatever you want but save the name and authentication key for later

Requesting Recording Data

Anytime a request is made to the API, an authentication key must be present. Use the auth key you saved above

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 CCaaS to have access to.

Request

Endpoint for requesting all recording data between a set period of time:

GET /rest/api/v2/recordings?startTime={startTime}&endTime={endTime}

You must use the ISO 8601 method for date/time ranges

Example: GET https://acmecorporate.xima.cloud/rest/api/v2/recordings?startTime=2022-09-10T23:59:59.000-06:00 &endTime=2022-09-11T23:59:59.000-06:00

Response

    {
        "recordingKey": "91a1e1e8-08p8-427b-bd04-da43c2a1db7d-1707770449131",
        "callKey": "1dd0gg18-9c63-41de-a386-4f21ba0086f2-1707770438499-1707770497510",
        "startTime": 1707770449131,
        "duration": 3606,
        "size": 9111,
        "eventId": 99181,
        "recordingSystemId": 0,
        "status": "SAVED",
        "callingParty": "18885553794",
        "receivingParty": "Spencer Porter(253)",
        "tenantName": "acme-ns",
        "tagData": "Default",
        "callDirection": "INBOUND",
        "skill": "CC Sales",
        "agent": "Spencer Porter(253)"
    },
    {
        "recordingKey": "a4bc65b6-24gh-41a7-a07b-0bcee2da6551-1707770466508",
        "callKey": "5dcf3a89-3c3b-47f2-a674-7884c2ee1054-1707770438499-1707770497510",
        "startTime": 1707770466508,
        "duration": 12806,
        "size": 16379,
        "eventId": 99184,
        "recordingSystemId": 0,
        "status": "SAVED",
        "callingParty": "18885551347",
        "receivingParty": "Kelly Jaques(256)",
        "tenantName": "acme-ns",
        "tagData": "",
        "callDirection": "INBOUND",
        "skill": "",
        "agent": "Kelly Jaques(256)"
    },

Request specific recording via recording ID

GET /rest/api/v2/recordings/{tenant-name}/{recording-key}/audio

Example: GET https://acmecorporate.xima.cloud/rest/api/v2/recordings/acme-ns/83849370-5753-4186-9fc5-9c069e615734-1568735345298/audio

Note that the tenant-name as collected from the JSON will need to be included in your request. That tenant-name will not change when collecting from a single site so feel free to hardcode it into your requests.

Response

📘

Opus Audio Format

The returned auto file will be OPUS, 8000Hz, Mono

If a successful request is made, then the response will be a file containing the audio (opus, mono, 8kbps) of the recording.

Expanded Metrics Available

With a recent update (April 2024), we've added the ability to pull additional metrics. The only change required is modifying the request slightly. You'll still get the same crucial metrics for recording collection (recording key and tenant name) but you'll also get other metrics about the recorded call.

The updated command is

GET /rest/api/v2/call-recording-info?startTime={startTime}&endTime={endTime}

 "callId": "853be5cc-f498-5D47-a552-a0b38e6841fc",
            "shortId": 31875,
            "callKey": "853be5cc-f498-4f33-a552-a0b38e6841fc-1712110317069-1712110924851",
            "startTime": 1712110317069,
            "endTime": 1712110924851,
            "direction": "INBOUND",
            "recordings": [
                {
                    "recordingKey": "fe417b58-34da-426c-8ffd-feca5fd772f4-1712110321584",
                    "callKey": "853be5cc-f498-4f33-a552-a0b38e6841fc-1712110317069-1712110924851",
                    "startTime": 1712110321584,
                    "duration": 603006,
                    "size": 341663,
                    "eventId": 101370,
                    "recordingSystemId": 0,
                    "status": "SAVED",
                    "callingParty": "13855554334",
                    "receivingParty": "Kelly Jaques(256)",
                    "tenantName": "acme-ns",
                    "tagData": "",
                    "callDirection": "INBOUND",
                    "skill": "",
                    "agent": "Kelly Jaques(256)"
                }
            ],
            "tenantName": "acme-ns",
            "callerId": "WIRELESS CALLER",
            "dialedPartyNumber": "7035559310",
            "accountCodes": [],
            "totalHoldDuration": 0,
            "location": "Reno, NV",
            "dropEventType": "DROP"
        }

Rate Limiting

To prevent excessive requests and unexpected egress costs, Xima has set rate limits for the API recording requests and in-app downloads.

Simultaneous API Request Limiting

Recording API requests should be received no more frequently than one per every 3 second per tenant

You are welcome to send very frequent requests to multiple tenants. You'll only have an issue if requesting more than 3 from a single tenant within 10 seconds so a good practice is 1 GET recording request to a tenant every 3 seconds or more.

If the request frequency limit is exceeded, you'll receive "429 Too Many Requests" errors.

Rolling Total Egress Limit

Xima has also enabled a 5-day rolling limit to ensure a site doesn't request well over the expected GB to cover their recording volume and needs. The assigned limit is based on the number of licensed recorded agents and providing nearly double the GB limit of what agents would recording full 8 hours shift. If the cap is met, the returned errors will be “509 Bandwidth Limit Exceeded”. If you feel this blocker is ever received in error, submit a ticket to Xima Support to review the usage and potentially reset the limit if the leak or bug has been addressed.

Potential Errors