Retrieving a Call Recording from a ConversationItem

Spruce’s API allows you to retrieve call recordings when your organization has call recording enabled and the ConversationItem originated from a phone call.

Requirements

• Call recording must be enabled for your organization.
• The ConversationItem must be from a phone call (inbound or outbound).

Where to Find the Recording

Call recordings are included in the event.data.recordings array within the ConversationItem. Each recording entry contains:

• mimetype (e.g. "audio/mpeg")
• signedUrl with a time-limited download link

Example Response

{
  "conversationItem": {
    "id": "ti_2G39MC0D8CO00",
    "createdAt": "2025-04-22T21:33:23Z",
    "direction": "outbound",
    "author": { "displayName": "T54W Home" },
    "conversationId": "t_2EJM2B5JJPO00",
    "text": "",
    "attachments": [],
    "event": {
      "type": "outboundCall",
      "data": {
        "answered": true,
        "duration": 21,
        "failed": false,
        "initiatedBy": { "lineId": "pl_2DHOCDOFAMO00" },
        "spam": false,
        "recordings": [
          {
            "mimetype": "audio/mpeg",
            "signedUrl": {
              "expiresAt": "2025-06-10T20:12:38Z",
              "url": "https://msg-media.sprucehealth.com/media/...<redacted>..."
            }
          }
        ]
      }
    }
  }
}

The call recording URL is located at event.data.recordings[0].signedUrl.url.

Retrieval Steps

1. Authenticate with the API using a bearer token. Refer to the Authentication Guide.

2. Fetch the conversation item using the ConversationItem API endpoint:

GET /conversationItem/{id}
Authorization: Bearer <your_api_token>

3. Extract the call recording URL from event.data.recordings[0].signedUrl.url.

4. Download the recording using a standard HTTP GET request to that URL.

Notes

• The signedUrl is time-limited. If expired, retrieve the conversation item again to obtain a new link.