Service Cloud Voice Implementation Guide
jNewer Version Available
Create Transcripts in Bulk
This API allows you to process transcripts quickly by creating multiple transcripts across different voice calls in one request. The transcript data is sent to the agent console synchronously in real time and persists in Salesforce asynchronously.
If your telephony provider can aggregate multiple transcripts across voice calls, use this API for faster processing, resulting in faster delivery to agents in real time. If your telephony provider is Amazon Connect and you use Contact Lens for Amazon Connect, this API is by default used to process your transcripts.
This API and the Create a Transcript API (/telephony/v1/voiceCalls/{vendorCallKey}/messages) share several characteristics.
- Both APIs create voice call transcripts if the timestamp of the transcript is between the start and end times of the conversation.
- Both APIs pause call transcription whenever the agent pauses the recording or places the call participant on hold. Any messages being sent in aren’t created or stored by the API during this time.
Where the two APIs differ is by the number of transcripts they can process per request. The Create a Transcript API only creates transcripts for one voice call at a time, while this API creates transcripts in bulk. Specifically, this API lets you create transcripts for up to five (5) different voice calls at a time, and each voice call can have up to five (5) transcripts. To make sure transcript entries are stored in chronological order, insert transcript data one participant at a time.
Since this API can contain transcripts for multiple voice calls, if an agent from one voice call pauses a recording or places a call participant on hold, transcription stops for just that voice call; the hold doesn’t interrupt transcription processing for the other voice calls.
To create or update transcripts in bulk after the call has ended, use the Salesforce Connect API.
URI
/telephony/v1/voiceCalls/messages
HTTP Method
POST
Headers
- Authorization: Bearer <token>
-
String. Standard header. The authorization token, where <token> is the JSON Web Token (JWT). Required.
- Content-Type: <format>
- String. Standard header. The format of the request body. Valid formats include JSON and XML. For example, application/json or application/xml. Required.
- Telephony-Provider-Name: <telephony provider name>
- String. Custom header. The name of the telephony provider that calls this API. For example, Amazon Connect.
Parameters
| Property Name | Type | Description | Required |
|---|---|---|---|
| entries | array | An array of create transcript objects for one or more voice call (VoiceCall) records. | Yes |
| vendorCallKey | string | The unique ID of the voice call (VoiceCall) record within the telephony system for which messages need to be created. | Yes |
| messages | array | An array of individual transcript objects for the voice call (VoiceCall) record. | Yes |
| participantId | string | The call participant that uttered this text.
|
Yes |
| messageId | string | The unique ID of the message. This value has to be unique for the given conversation. | Yes |
| startTime | int64 | The date and time (in UTC) when this utterance started. Measured in milliseconds since the Unix epoch. | Yes |
| endTime | int64 | The date and time (in UTC) when this utterance ended. Measured in milliseconds since the Unix epoch. | Yes |
| content | string | The actual text of the utterance. | Yes |
| senderType | string | The voice call participant role that generated the utterance. Possible values are:
|
Yes |
Example
Request:
1POST /telephony/v1/voiceCalls/messages
2
3{
4 "entries": [
5 {
6 "vendorCallKey": "b09955ce-03be-4335-a28891293zs-18895",
7 "messages": [
8 {
9 "startTime": 1573503300000,
10 "endTime": 1573503300001,
11 "participantId": "b09955ce-03be-4335-a28891293zs-18895END_USER",
12 "messageId": "b09955ce-03be4335xz-a28891293zs",
13 "senderType": "END_USER",
14 "content": "Hello All"
15 },
16 {
17 "startTime": 1573503300002,
18 "endTime": 1573503300003,
19 "participantId": "b09955ce-03be-4335-a28891293zs-18895VIRTUAL_AGENT",
20 "messageId": "b09955ce-03be4335ej-a28891293sz",
21 "senderType": "VIRTUAL_AGENT",
22 "content": "Hello All"
23 }
24 ]
25 },
26 {
27 "vendorCallKey": "b09955ce-03be-4335-a28891293sz-188952",
28 "messages": [
29 {
30 "startTime": 1573503300012,
31 "endTime": 1573503300013,
32 "participantId": "VIRTUAL_AGENT",
33 "messageId": "b2922012ne-t13081984si-t04021978re",
34 "senderType": "b09955ce-03be-4335-a28891293sz-188952VIRTUAL_AGENT",
35 "content": "Hello All"
36 }
37 ]
38 },
39 {
40 "vendorCallKey": "b01211ce-03be-4335-a28891293sz-188978",
41 "messages": [
42 {
43 "startTime": 1573503300000,
44 "endTime": 1573503300001,
45 "participantId": "005123456789abc",
46 "messageId": "a2922012ne-t13081984si-t04021978re",
47 "senderType": "HUMAN_AGENT",
48 "content": "Hello everyone"
49 },
50 {
51 "startTime": 1573503300002,
52 "endTime": 1573503300003,
53 "participantId": "a12355ce-03be-4335-a28891293sz",
54 "messageId": "b09955ce-03be4335ej-a28891293sz",
55 "senderType": "EXTERNAL_USER",
56 "content": "Hello"
57 }
58 ]
59 }
60 ]
61}Response:
1// All transcripts were successfully processed.
2{
3 "result": "Accepted"
4}Response with errors:
1// A multi-status error occurred, meaning one or more messages in the request weren’t processed due to an error.
2{
3 "result": "Multi-Status: A few messages were not processed",
4 "errorResponse": {
5 "errorResponseEntries": [
6 {
7 "vendorCallKey": "b09955ce-03be-4335-saturday-18896",
8 "status": 400,
9 "message": "Error Processing Transcript with Id(s) [b09955ce-03be-4335-a8a0-2889129]. Error: io.grpc.StatusRuntimeException: PERMISSION_DENIED: Conversation does not exist"
10 },
11 {
12 "vendorCallKey": "b09955ce-03be-4335-saturday-188954",
13 "status": 202,
14 "message": "Successfully Processed Transcripts with Id(s) [b2922012ne-t13081984si-t04021978re]"
15 },
16 {
17 "vendorCallKey": "ghbjnkk-jlme-6789-friday-67754",
18 "status": 400,
19 "message": "Error Processing Transcript with Id(s) [kjikjnkk-jkjhu-6789-kjgjhg-87643]. Error: io.grpc.StatusRuntimeException: PERMISSION_DENIED: Conversation does not exist"
20 }
21 ]
22 }
23}