Service Cloud Voice Implementation Guide

Overview
Release Notes
Examples of Common Use Cases
Telephony Integration API
Authorization
Create a Voice Call Record
Update a Voice Call Record
Create a Transcript
Create Transcripts in Bulk
Execute an Omni-Channel Flow
Route a Voice Call
Request a Callback
Send a Real-Time Conversation Event
Store a Post-Call Conversation Event
Reroute a Voice Call
Clear Routing
Sample Code
Toolkit API
Connect API
AWS Lambda Functions
Amazon Connect Flows
Amazon CloudWatch Monitoring
Limits and Scaling
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Create Transcripts in Bulk

Creates transcripts in bulk across multiple voice calls in real time. These voice calls can include inbound calls, transfer calls, outbound calls, callback calls, and consult calls.

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 rep 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 reps 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 rep 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.

The APIs also differ in terms of their capacity.

  • The Create a Transcript API creates a transcript for one voice call only.
  • This Create Transcripts in Bulk API lets you create transcripts for up to 5 different voice calls at a time. Each voice call included in the payload can have up to 5 transcripts (also called conversation entries).

To make sure conversation entries are stored in chronological order for this API, insert transcript data one participant at a time. For example, include a one-sided conversation with entries from the end user in the messages object. For a sender type of VIRTUAL_AGENT, include conversation entries from multiple reps in the messages object, in order of utterance.

Since this API can contain transcripts for multiple voice calls, if a rep 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 or to upload a binary file of transcripts up to 512 MB, 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.
  • If senderType is END_USER, set this value to {vendorCallKey}END_USER, where {vendorCallKey} is the vendor call key (vendorCallKey) of the first voice call (VoiceCall) record created for the conversation. For consult calls that haven't been merged with a multiparty call, {vendorCallKey} is the vendorCallKey of the VoiceCall created for the consult call. If you set this property to any other value, Salesforce sets it to {vendorCallKey}END_USER internally for privacy reasons.
  • If senderType is EXTERNAL_USER, set this value to the unique ID for the external call participant generated by the telephony partner.
  • If senderType is HUMAN_AGENT, enter the rep’s 15-digit or 18-digit Salesforce user ID (starts with 005).
  • If senderType is SUPERVISOR, set this value to{vendorCallKey}SUPERVISOR, where {vendorCallKey} is the vendor call key (vendorCallKey) of the first voice call (VoiceCall) record created for the conversation. If you set this property to any other value, Salesforce will set it to {vendorCallKey}SUPERVISOR internally for privacy reasons.
  • If senderType is VIRTUAL_AGENT, set this value to {vendorCallKey}VIRTUAL_AGENT, where {vendorCallKey} is the vendor call key (vendorCallKey) of the first voice call (VoiceCall) record created for the conversation. If you set this property to any other value, Salesforce sets it to {vendorCallKey}VIRTUAL_AGENT internally for privacy reasons.
 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:
  • END_USER - Represents a customer.
  • EXTERNAL_USER - Represents a contact external to your Salesforce organization.
  • HUMAN_AGENT - Represents a rep.
  • SUPERVISOR - Represents a supervisor. For example, a supervisor generates an utterance when they barge into a call between a customer and rep and start talking.
  • VIRTUAL_AGENT - Set this value to VIRTUAL_AGENT when you have a conference between multiple reps and you want to create all rep-side utterances as one single rep since you have no way to differentiate between the different reps in the audio stream. The sender in this case must be the vendor call key (vendorCallKey) of the first voice call (VoiceCall) record created for the conversation.
Yes

Example

Request:

1POST /telephony/v1/voiceCalls/messages
2
3{
4  "entries":  [
5    {
6      "vendorCallKey": "abc955ce-03be-4335-a28891293zs-12267",
7      "messages":  [
8        {
9          "startTime": 1770307118000,
10          "endTime": 1770307120500,
11          "participantId": "abc955ce-03be-4335-a28891293zs-12267END_USER",    
12          "messageId": "a09955ce-03be4335xz-a28891293zs",
13          "senderType": "END_USER",
14          "content": "Hi, I need help with my plane reservation."
15        },
16        {
17          "startTime": 1770307125000,
18          "endTime": 1770307128200,
19          "participantId": "abc955ce-03be-4335-a28891293zs-12267END_USER",    
20          "messageId": "c09955ce-03be4335xz-a28891293zu",
21          "senderType": "END_USER",
22          "content": "Yes, it was canceled."
23        },
24        {
25          "startTime": 1770307132000,
26          "endTime": 1770307134100,
27          "participantId": "abc955ce-03be-4335-a28891293zs-12267END_USER",    
28          "messageId": "d09955ce-03be4335xz-a28891293zw",
29          "senderType": "END_USER",
30          "content": "Do you have anything direct?"
31        },
32        {
33          "startTime": 1770307139000,
34          "endTime": 1770307142500,
35          "participantId": "abc955ce-03be-4335-a28891293zs-12267END_USER",    
36          "messageId": "f09955ce-03be4335xz-a28891293zz",
37          "senderType": "END_USER",
38          "content": "Yes, that should work."
39        },
40        {
41          "startTime": 1770307147000,
42          "endTime": 1770307149800,
43          "participantId": "abc955ce-03be-4335-a28891293zs-12267END_USER",    
44          "messageId": "g09955ce-03be4335xz-a28891293zx",
45          "senderType": "END_USER",
46          "content": "Thanks for your help."
47        }
48      ]
49    },
50    {
51      "vendorCallKey": "b09955ce-03be-4335-a28891293zs-18895",
52      "messages":  [
53        {
54          "startTime": 1770307800000,
55          "endTime": 1770307802800,
56          "participantId": "b09955ce-03be-4335-a28891293zs-188955END_USER",    
57          "messageId": "1b9955ce-03be4335xz-a28891293zu",
58          "senderType": "END_USER",
59          "content": "Hi, I'd like to ask about an upgrade."
60        },
61        {
62          "startTime": 1770307808200,
63          "endTime": 1770307811900,
64          "participantId": "b09955ce-03be-4335-a28891293zs-18895END_USER",    
65          "messageId": "b23455ce-03be4335xz-a28891293zu",
66          "senderType": "END_USER",
67          "content": "Yes, for my trip next month."
68        },
69        {
70          "startTime": 1770307818000,
71          "endTime": 1770307820500,
72          "participantId": "b09955ce-03be-4335-a28891293zs-18895END_USER",    
73          "messageId": "b09955ce-03be4335xz-a28891293zu",
74          "senderType": "END_USER",
75          "content": "Perfect, thanks."
76        }
77      ]
78    },
79    {
80      "vendorCallKey":  "m07855ce-03be-4335-a28891293zs-78543",
81      "messages":  [
82        {
83          "startTime": 1770308400000,
84          "endTime": 1770308403200,
85          "participantId": "m07855ce-03be-4335-a28891293zs-78543END_USER",    
86          "messageId": "m86655ce-03be4335xz-a28891293zw",
87          "senderType": "END_USER",
88          "content": "I have a complaint about my meal."
89        },
90        {
91          "startTime": 1770308409500,
92          "endTime": 1770308412100,
93          "participantId": "m07855ce-03be-4335-a28891293zs-78543END_USER",    
94          "messageId": "n5998ce-03be4335xz-a28891293zw",
95          "senderType": "END_USER",
96          "content": "It was so delicious I wish it was bigger."
97        }
98      ]
99    },
100    {
101      "vendorCallKey": "k18968ce-03be-4335-a28891293zs-98736",
102      "messages":  [
103        ...
104      ]
105    },
106    {
107      "vendorCallKey": "s79758ce-03be-4335-a28891293zs-48346",
108      "messages":  [
109        ...
110      ]
111    }
112  ]
113}

Request:

1POST /telephony/v1/voiceCalls/messages
2
3{
4  "entries": [
5    {
6      "vendorCallKey": "5324881f-1e84-4367-8930-f69a74b30ca6",
7      "messages": [
8        {
9          "startTime": 1770309300000,
10          "endTime": 1770309302500,
11          "participantId": "5324881f-1e84-4367-8930-f69a74b30ca6VIRTUAL_AGENT",
12          "messageId": "8hjcd32b-bb06-477b-8947-74660b4db74g",
13          "senderType": "VIRTUAL_AGENT",
14          "content": "My colleague in the service department has joined our call."
15        },
16        {
17          "startTime": 1770309309000,
18          "endTime": 1770309312200,
19          "participantId": "5324881f-1e84-4367-8930-f69a74b30ca6VIRTUAL_AGENT",
20          "messageId": "6gjcd32b-bb06-477b-8947-74660b4db74g",
21          "senderType": "VIRTUAL_AGENT",
22          "content": "Hi, I'm going to help you with your service appointment rescheduling."
23        },
24        {
25          "startTime": 1770309319000,
26          "endTime": 1770309321800,
27          "participantId": "5324881f-1e84-4367-8930-f69a74b30ca6VIRTUAL_AGENT",
28          "messageId": "4jfcd32b-bb06-477b-8947-74660b4db74g",
29          "senderType": "VIRTUAL_AGENT",
30          "content": "I'll let our service department take it from here."
31        }
32      ]
33    },
34    {
35      "vendorCallKey": "5324881f-1e84-4367-8930-f69a74b30ca6",
36      "messages": [
37        {
38          "startTime": 1770309480000,
39          "endTime": 1770309483000,
40          "participantId": "5324881f-1e84-4367-8930-f69a74b30ca6VIRTUAL_AGENT",
41          "messageId": "1efcd32b-bb06-477b-8947-74660b4db74m",
42          "senderType": "VIRTUAL_AGENT",
43          "content": "Thank you. Just one minute while we look up your account number."
44        },
45        {
46          "startTime": 1770309489500,
47          "endTime": 1770309492100,
48          "participantId": "5324881f-1e84-4367-8930-f69a74b30ca6VIRTUAL_AGENT",
49          "messageId": "9sdcd32b-bb06-477b-8947-74660b4db74m",
50          "senderType": "VIRTUAL_AGENT",
51          "content": "We're both here to help your with your request. Can you provide more information?"
52        }
53      ]
54    },
55    {
56      "vendorCallKey": "9273881f-1e84-4367-8930-f69a74b30ab8",
57      "messages": [
58        {
59          "startTime": 1770309660000,
60          "endTime": 1770309664500,
61          "participantId": "9273881f-1e84-4367-8930-f69a74b30ab8VIRTUAL_AGENT",
62          "messageId": "1efcd32b-bb06-477b-8947-74660b4db74z",
63          "senderType": "VIRTUAL_AGENT",
64          "content": "Thank you for your patience. Now that my teammate has joined, let's address your issue."
65        }
66      ]
67    }
68  ]
69}

Response:

1// All transcripts were successfully processed.
2{
3  "result": "Accepted"
4}