Every Digital Task contains a collection of messages that are exchanged between the business (spanning both AI agents and Human agents) and the end customer. While practically these messages may involve rich messaging entities (such as carousel, quick replies, etc.), the Captures API flattens these messages into simple text that are human readable and can be posted to external systems thereby avoiding the overhead of parsing wide varieties of rich messaging JSON objects.

anchorQuick Recap - Captures API

Before we understand the details of the transcript we receive, let's go through a quick recap of Captures. For further details around this, you can refer to the Captures API Reference

Authorization

While Webex CC's Developer APIs support both User Tokens and Service App Tokens, we strongly recommend leveraging Service App based Authentication in case you are building machine to machine integrations (for e.g. to write data into external CRM systems, etc.). This ensures that your App integration tokens do not expire when a user leaves your org (or) their license is revoked

Request

curl --location --request POST 'https://{{api-base-domain}}/v1/captures/query' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data-raw '
{
     "query": {
          "orgId": "{{orgId}}",
          "urlExpiration": {{TimeInMinutes}}, // Minimum: 10, Maximum: 60
          "taskIds": [
               "{{taskId1}}",
               "{{taskId2}}",
               "..." // Maximum: 10 tasks
          ],
          "includeSegments": false
     }
}
'

For more details on how to fetch an access token, please refer to the Authorization section above.

Response

This guide assumes that you've been able to get a success response from Captures API. For other error scenarios, please refer to the Captures API Reference.

Success HTTP Code: 200 OK

Success Response Body:

{
  "meta": {
    "orgId": "{{orgId}}",
    "urlExpiration": "{{TimeInMin}}"
  },
  "data": [
    {
      "taskId": "{{taskId1}}",
      "recording": [],
      "transcription": [
        {
          "source": "{{channelType}}",
          "provider": "CISCO",
          "id": "{{taskId}}",
          "fileName": "{{channelType.json}}",
          "filePath": "{{S3 Presigned URL to download transcript JSON}}",
          "startTime": "{{TimeInMs}}",
          "languageCode": "en",
          "configId": "{{mediaResourceId}}",
          "createTime": "{{TimeInMs}}"
        }
      ]
    },
    {
      "taskId": "{{taskId2}}",
      "recording": [],
      "transcription": [
        {
          "source": "{{channelType}}",
          "provider": "CISCO",
          "id": "{{taskId}}",
          "fileName": "{{channelType.json}}",
          "filePath": "{{S3 Presigned URL to download transcript JSON}}",
          "startTime": "{{TimeInMs}}",
          "languageCode": "en",
          "configId": "{{mediaResourceId}}",
          "createTime": "{{TimeInMs}}"
        }
      ]
    }
  ]
}

anchorDealing with Captures API Response

Follow the below steps to get to the digital transcript:

1. From the json response above, parse the attribute filePath. The filePath points to a pre-signed URL containing a transcript.json file specific to the interactionId in context. The validity of this URL would honor the urlExpiration attribute specified in the request file.

2. Make a HTTP GET request to the filePath URL. This will ideally return a json response that will contain a response as mentioned below if your request is successful:

Digital Transcript JSON

The object below will be referred to as the transcript.json from here on in this guide.

[
  {
    "id": "00ef01b1-ae08-4434-9874-98bc34766164",
    "aliasId": "00ef01b1-ae08-4434-9874-98bc34766164",
    "direction": "inbound",
    "message": "Form Response: Name - John Doe, Email - john@live.com",
    "attachments": null,
    "participant": {
      "name": "John Doe",
      "role": "customer",
      "userId": "",
      "aliasId": ""
    },
    "timestamp": "2023-11-07T13:24:09:024Z",
    "redacted": false
  },
  {
    "id": "72c2254351e543aa98ac5c40fe837009",
    "aliasId": "72c2254351e543aa98ac5c40fe837009",
    "direction": "outbound",
    "message": "We are currently out of office and services ",
    "attachments": [
      {
        "fileName": "Sample Image 1.png",
        "mimeType": "image/png",
        "url": "https://{{media-regional-sub-domain}}.s3.amazonaws.com//digital/transcripts/56a2cef6-a1b3-43cd-b97a-036f3edae8bf/chat/bd0b90d8-92d0-4550-85fe-48bb4d274e30/attachments/8e0ebdc5-169d-443d-8fa9-ae53b9a9ae69/BE0EB707-56F9-4A32-9C70-17FD4D706AFFSample Image 1(1).PNG?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250424T104747Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIATRZUOXQOOEF7E2MR/20250424/us-east-1/s3/aws4_request&X-Amz-Signature=f44257d7869ef2f2300984ae84d0494205388d46e0f1e60ff57aca93c3012f78&JWE=eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..jj40-zAvLZBVzGie.QTtrp7RnZVkaBPy5ZVynNMJU_9yDkE55s-wZJMU7QPQHbXTPFEq8gxUexNmk9JIOknUeckwrzEaDCDKi-xh8jWZ_fYgrUdSej_GXU4L_FmDjQGOzIRRCAyj9_X8xmM4RBbI56Se6UNYpK0ULeCWpk6DkeWSYmykhw82Pal4NwhS-LY6aXpvZRBkY4Arc8V7R9z3P3HCOkuoN1c2SxeadiepsILwY5x7gSo7zan-HHNLGkOigB8qrb65E19QBJUb3mrdMHsKLYJi6cRBOwzjBeqyfpOq5tfAStIdJMW-yQduvV39Cufyo1rswBz1eBKWBBGThuw8CYaDBtlJ5I1sVtwqLsQDJSnb17hJJaKbSDTlJtxUhUiEoL9xhG0jtWwZCDJnk0cqWhkvyzPI7hAl5JMw9J5kWZkP4BcKvKdV9wbO-zHTSyWMV0i-g-eFWrTTTK4n25pUjkBXVXf8jKCde22-nmsdmaq52ILo.TxZRACWOaay6A-56EvHdPg&keyUri=kms://kms-us-int.wbx2.com/keys/d1991610-2184-4c84-8204-5d8a5a361e69",
        "dropped": true,
        "encrypted": false,
        "encryptionDetails": {
          "jwe": "",
          "keyUri": ""
        }
      },
      {
        "fileName": "Sample Text.txt",
        "mimeType": "image/jpeg",
        "url": "https://{{media-regional-sub-domain}}.s3.amazonaws.com//digital/transcripts/56a2cef6-a1b3-43cd-b97a-036f3edae8bf/chat/bd0b90d8-92d0-4550-85fe-48bb4d274e30/attachments/8e0ebdc5-169d-443d-8fa9-ae53b9a9ae69/BE0EB707-56F9-4A32-9C70-17FD4D706AFFSample Text(1).TXT?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250424T104747Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3599&X-Amz-Credential=AKIATRZUOXQOOEF7E2MR/20250424/us-east-1/s3/aws4_request&X-Amz-Signature=f44257d7869ef2f2300984ae84d0494205388d46e0f1e60ff57aca93c3012f78&JWE=eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..jj40-zAvLZBVzGie.QTtrp7RnZVkaBPy5ZVynNMJU_9yDkE55s-wZJMU7QPQHbXTPFEq8gxUexNmk9JIOknUeckwrzEaDCDKi-xh8jWZ_fYgrUdSej_GXU4L_FmDjQGOzIRRCAyj9_X8xmM4RBbI56Se6UNYpK0ULeCWpk6DkeWSYmykhw82Pal4NwhS-LY6aXpvZRBkY4Arc8V7R9z3P3HCOkuoN1c2SxeadiepsILwY5x7gSo7zan-HHNLGkOigB8qrb65E19QBJUb3mrdMHsKLYJi6cRBOwzjBeqyfpOq5tfAStIdJMW-yQduvV39Cufyo1rswBz1eBKWBBGThuw8CYaDBtlJ5I1sVtwqLsQDJSnb17hJJaKbSDTlJtxUhUiEoL9xhG0jtWwZCDJnk0cqWhkvyzPI7hAl5JMw9J5kWZkP4BcKvKdV9wbO-zHTSyWMV0i-g-eFWrTTTK4n25pUjkBXVXf8jKCde22-nmsdmaq52ILo.TxZRACWOaay6A-56EvHdPg&keyUri=kms://kms-us-int.wbx2.com/keys/d1991610-2184-4c84-8204-5d8a5a361e69",
        "dropped": true,
        "encrypted": true,
        "encryptionDetails": {
          "jwe": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..ZkI-74v_XN9u_Tu3.ehNpfTXjlF3RuMmCILOp_H_cPj8FP7ggaryqPS5T0BUWC5PVETKZqIQDOjZJa5OC06y8SYkPfBZkimt52pC3NE-cowrv-VzRq1agmYmn6jiVlNsy3ktZcQfgY3w3nj6EmElo6fnAsdaGZVo79SXuU8GPegJMEIoNKNAEFmr_sVFNle-8XSDdfpirs3JKKZqe_9iN-4lR7xd4-vNBP1dqVIlP17_3mIFbL8WMT6L_z4WX7Bi76k8rQfVIidA1M_psLG9iwvM7o_2Nd-BcbRwlnUg4--cJnXwsk3PSi2wIchwLO-WCjfkxigM2H70YCNbFKGhGjmi_YLpi5hoe9_ryMC7UnOK_rKYOwZF1E7kMlEfc9S5k2GhQxxOYdL73qgnyk0UfoZ2aBoUlAgvnRlgbX78rO1t94lL9TUL9RPF71OhNre4JaXuPR6gOmyofMOpWWnMxj_hTFOd4lcIpocb6kmYJRwvcYERFdecqruFVEiydwmB8IQy4eFdsJWkDaSswRA.XqVlRCZUovATcaNPXqL2Pg",
          "keyUri": "kms://kms-us-int.wbx2.com/keys/8fd281bd-47e0-4b3a-b438-6ea289e64ea2"
        }
      }
    ],
    "participant": {
      "name": null,
      "role": "agent",
      "userId": "New Conversation",
      "aliasId": ""
    },
    "timestamp": "2023-04-06T11:49:39:897Z",
    "redacted": false
  }
]

1. The transcript.json contains an array of individual messages exchanged between the business and the end-customer.

2. You can now loop through each of the items in this array to access relevant information about the message object such as message, timestamp, attachments, etc.

We have published a table below under the section: Transcript JSON Schema Details that explains these fields in further detail for your reference.

anchorDecrypting Attachments

1. Encrypted attachments will need to be decrypted using Webex Encryption SDK made available to developers. In order to do this, you'll need the following parameters handy from the transcript.json

• attachments[i].url
• attachments[i].encrypted
• attachments[i].encryptionDetails

1. Webex Developer Platform offers a Webex JS SDK encryption plugin that will allow you to decrypt these attachments.
2. Install the Decryption SDK

npm install --save @webex/plugin-encryption

1. Below is a sample code that you would need to use in order to decrypt attachments

import Webex from "@webex/plugin-encryption";
import fs from "fs";

// Initialize Webex with access token
const webex = Webex.init({
  credentials: {
    access_token: accessToken,
  },
});

// Example attachment URL from the transcript JSON
const attachmentUrl =
  "https://example.com/attachment-url?keyUri=somekeyuri&JWE=someJweValue";
const fileName = "myfile.jpg";

webex.once("ready", async () => {
  try {
    // Register the cypher
    await webex.cypher.register();

    // The attributes - `jwe` and `keyUri` are to be fetched from the `attachments` array object from the `transcript.json`
    const options = {
      useFileService: false,
      // If JWE or keyUri are not in the URL, you would need to provide them:
      // jwe: 'yourJweValue',
      // keyUri: 'yourKeyUriValue'
    };

    const fileBytes = await webex.cypher.downloadAndDecryptFile(
      attachmentUrl,
      options
    );

    fs.writeFileSync(fileName, fileBytes);
    console.log(`File saved to ${fileName}`);

    // Deregister when done
    await webex.cypher.deregister();
  } catch (error) {
    console.error("Error in encryption process:", error);
    await webex.cypher.deregister();
  }
});

anchorTranscript JSON Schema Details