Service Cloud Voice Implementation Guide

Overview
Contact Flows
Examples of Common Use Cases
Lambda Functions
Telephony Integration REST API
Create a Voice Call Record
Update a Voice Call Record
Create a Transcript
Execute an Omni-Channel Flow
Clear Routing
Sample Code
Authorization
Customer Alerts with CloudWatch
Toolkit API
Connect API to Update Transcripts
Limits and Scaling
PDF

Newer Version Available

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

Create a Voice Call Record

Creates a voice call (VoiceCall) record containing the participants (that is, the caller and recipient) in the call.

When you create a voice call record, it creates a conversation in Salesforce. Only use this API in real time, which means that you should invoke this API only when a call is initiated.

This API can also be used to create voice call records for transfer by including the parentVoiceCallId parameter in the request payload.

URI

/telephony/v1/voiceCalls

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
callCenterApiName string The API name of the contact center created in Salesforce associated with the voice call record. Yes
parentVoiceCallId string For transfers, set this value to a Salesforce Voice Call record ID or the voice call’s vendor call key (vendorCallKey) representing the parent record to this newly created voice call record. This parameter is required if initiationMethod=transfer

Only use this property to create voice call records for transfer. Don’t include this property when creating the initial voice call record.

 No
vendorCallKey string A unique key that identifies the voice call record within the telephony system. For example, if the telephony system is Amazon Connect, this value is the contact ID in Amazon Connect.

If another voice call record with the same vendor call key already exists, a new voice call record won’t be created. Instead, Salesforce returns the Salesforce voice call ID of the existing voice call record with this vendor call key.

 Yes
to string The phone number to where the voice call is made. For inbound calls and transfers, set this value to the contact center’s phone number. Yes
from string The phone number from where the voice call is made or transferred.
  • For inbound calls, set this value to the end user's phone number.
  • For transfers, set this value to the contact center's phone number.
 Yes
initiationMethod string The initiation method of the voice call.
Possible values are:
  • Inbound. Represents a voice call that originated from an inbound call.
  • Transfer. Represents a voice call that was transferred from another agent. If initiationMethod=transfer, then parentVoiceCallIdmust also be set.
Outbound calls aren’t supported.
Yes
startTime string The date and time (in UTC) when the voice call started. Yes
participants array The end-user participant on the voice call. Only one end user can be specified. If there are multiple people in the array, the first person is assigned as the end user.

This property uses the following key-value pair, where participantKey is any unique identifier for the end user, and type is always "END_USER":

1{
2  "participantKey": "UNIQUE ID FOR THE END USER",
3  "type": "END_USER"
4}
For example, 
1{
2  "participantKey":"5324881f-1e84-4367-8930-f69a74b30ca6", 
3  "type": "END_USER"
4}
Note: While participantKey takes the end user’s unique identifier, Salesforce internally sets it to “END_USER” for privacy reasons.		 Yes
callAttributes string Represents additional standard and custom fields in the voice call record, where each key-value pair value corresponds to a standard or custom field and its values.
Possible standard fields are:
  • SourceType - Represents the general purpose of the call. Valid values are: Sales and Service.
  • ToPhoneNumber - Represents the recipient of the phone call.
Here’s an example using the standard field SourceType:
1"callAttributes": "{\"SourceType\":\"Sales\"}"
Here's an example using a custom field named "Department__c":
1[
2  "callAttributes": "{\"Department__c\":\"Support\", \"Sales\"}"
3}
This property is ignored when creating a voice call record for transfer. 		No

Example

Request:

1POST /telephony/v1/voiceCalls
2
3{
4  "callCenterApiName": "MyContactCenter",
5  "vendorCallKey": "5324881f-1e84-4367-8930-f69a74b30ca6",
6  "to": "8002345678",
7  "from": "4081456688",
8  "initiationMethod": "Inbound",
9  "startTime": "2019-07-02T17:32:28Z",
10  "participants": [
11    {
12      "participantKey": "4081456688",
13      "type" : "END_USER"
14    }
15  ],
16  "callAttributes": "{\"MyField__c\": \"abc\"}"
17}
Response without any errors:
1{
2  "voiceCallId": "0LQRM0000006CSz",
3  "errors": []
4}
Response with errors:
1{ 
2  "voiceCallId": "0LQRM0000001qEy", 
3  "errors": ["SocialSecurity__c: data value too large: 123456", "NumberField__c: invalid number: bad"]
4}