Service Cloud Voice Implementation Guide

Overview
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
Send a Real-Time Conversation Event
Store a Post-Call Conversation Event
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 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
callOrigin string Information about how this call originated.
Possible values are:
  • Preview. Represents a preview dialer.
  • Progressive. Represents a progressive dialer.
  • Voicemail. Represents a voicemail call.
 No
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 is set to Transfer, parentVoiceCallId must also be set.
Outbound calls aren’t supported.
Yes
queue string

Optional queue ID to associate with this voice call. This parameter is only used when initiationMethod is set to Transfer. It’s ignored for other initiation methods.

You can pass in either the Salesforce queue object ID or the vendor’s external queue ID. Salesforce resolves this value using the entries in the CallCenterRoutingMap record.

If the queue is resolved to a valid Salesforce queue, the VoiceCall owner is changed to the queue and the supervisor is able to see the transferred call waiting in the queue.

See Map Your Salesforce Queues to Telephony Provider Queues.

 No
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":

For example,
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:
Here's an example using a custom field named "Department__c":
 No

Example

Request:

Response:

You may encounter errors when creating a voice call record. These errors can be caused by a number of factors due to triggers, flows, required fields, and field validations. Salesforce bypasses the errors, creates the voice call record, and returns an errors response like the one in the following example.

Note