GuidesAPI EndpointsKnowledge BaseSupportTalkdesk WebsiteMarketplaceDiscussionsDevelopers Blog

Toggle Recordings API

Suggest Edits

Overview

Allows controlling, privately and programmatically, the recording status of an ongoing interaction between an agent and a caller.

📘

Pause Recordings Functionality

Comparable to the Talkdesk Recording Controls feature.

👍

Access and Registration

Authentication

Usage

1 - Identify the Talkdesk user given an email (process of pausing the recording for a handled interaction given a user email):

There are two main options when it comes to identifying the Talkdesk user who is in an interaction whose recording is to be paused:

  • For interactive flows, where the app that wants to pause a recording is running in the users' browser, it’s recommended integrating with Talkdesk Single Sign-On.
  • For background app that authenticate using client credentials, Users API can be utilized to match an email address with a list of potential Talkdesk users:
Field NameTypeDescription
EmailStringThe email address of the user handling an interaction

Sample Request 

GET https://api.talkdeskapp.com/[email protected] HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

curl https://api.talkdeskapp.com/users/[email protected] \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json'

Sample Response 

{
  "total": 2,
  "page": 1,
  "per_page": 1,
  "_embedded": {
    "users": [
      {
        "id": "c65186ee-3780-468e-968b-ca15b981c312",
        "email": "[email protected]",
        "name": "John Smith",
        "active": true,
        "gender": "Male",
        "extension": 123,
        "external_phone_number": "+18000000000",
        "created_at": "2016-06-14T16:23:07Z",
        "_links": {
          "self": {
            "href": "https://api.talkdeskapp.com/users/{user_id}"
          },
          "account": {
            "href": "https://api.talkdeskapp.com/account"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.talkdeskapp.com/users"
    },
    "account": {
      "href": "https://api.talkdeskapp.com/account"
    },
    "next": {
      "href": "https://api.talkdeskapp.com/users?page=2"
    }
  }
}

2 - Map the current interaction

Given that the Talkdesk user that is handling the interaction is known by a user_id, the Presence API can be used to get real-time information about the agent status and occupancy.

The Presence API provides specific mappings to ongoing interactions the user is handling, and this can be leveraged to find the interaction_id.

🚧

The Presence API is in Early Access. Contact a Customer Success Manager or [email protected] to enable it.

Sample Request 

GET https://api.talkdeskapp.com/users/{id}/presence HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

curl https://api.talkdeskapp.com/users/{id}/presence \
-H "Authorization: Bearer ACCESS_TOKEN"
-H "Content-type: application/json"

Sample Response 

{
"account_id": "5a4f5c04522953000bccca75",
"user_id": "59df62c81507b35a7cf2bbd3",
"status": "away",
"custom_status": "away_custom",
"occupancy": 100,
"channels": [ ... ],
"devices": [ ... ],
"interactions": [
{
"id": "59df62c81507b35a7cf2bbd4", 
"device_id": "some_id_1",
"channel_name": "voice",
"cost": 100
}
],
"updated_at": "2018-02-28T15:08:54:02Z"
}

The interaction_id of the current interaction being handled by the agent can be retrieved from the response.

3 - Pausing or resuming the recording

The interaction_id issues the command to pause or to start the call recording.

Sample request (pausing the recording) 

POST https://api.talkdeskapp.com/interactions/{interaction_id}/actions/pause_recording HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/json

Sample request (starting the recording) 

POST https://api.talkdeskapp.com/interactions/{interaction_id}/actions/start_recording HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

📘

Response Handling

  • If the return is an HTTP success status code (2xx), the operation was successful. If there is an error in the process, the operation can be can rerun. There are no other side effects except pausing the recording.
  • An HTTP success status code is returned if the request is made and the interaction recording status is as expected.

Scopes

users:read

presence-user:read

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.

Updated 6 months ago