Skip to main content
Version: 2.8

Service Cloud Voice API Wrapper

Pre-requisites​

In order to use the Service Cloud Voice API Wrapper, a Salesforce Connected App for IVR integration must be configured.

Use the Service Cloud Voice API Wrapper​

Service Cloud Voice (SCV) for Salesforce uses the Telephony Integration REST API to create and update VoiceCalls, execute Omni-Channel flows and delete PendingServiceRouting records associated to a VoiceCall. This service requires JWT authorization and the use of the PATCH HTTP method, which is currently not supported by the Cisco IP Interactive Voice Response (IVR).

In order to simplify the usage of the Telephony Integration REST API for SCV in (not only) an IVR system, a new set of APIs have been made available, which wrap the existing Salesforce API and are accessible directly from the Salesforce Org where the b+s Connects for Service Cloud Voice package is installed.

The Service Cloud Voice API Wrapper removes the need of authenticating a JWT token, implements additional checks on the data required by the Salesforce API and improves the response objects.

Retrieve the Access_Token​

Execute a POST request to https://<your-domain-name>.my.salesforce.com/services/oauth2/token

Sending the following parameters in the body:

{
    "grant_type": "client_credentials",
    "client_id": "<consumer key of the connected app>",
    "client_secret": "<consumer secret of the connected app>"
}

If the request is successful, the following JSON response will be returned:

{
    "access_token": "<your-access-token>",
    "instance_url": "<your-org-base-url>",
    "id": "https://login.salesforce.com/id/<id>/<id>",
    "token_type": "Bearer",
    "issued_at": "<timestamp>",
    "signature": "<unique-signature-code>"
}

Execute the requests​

The instance url must contain my.salesforce.com.
Example of a correct instance url: https://abc-123.my.salesforce.com

Using any other domain as instance url (i.e. https://abc-123.lightning.force.com) will result in a 401 Unauthorized status with a INVALID_SESSION_ID errorCode returned.

Create Voice Call​

Creates a VoiceCall record containing the participants (that is, the caller and recipient) for the VoiceCall record. When you create a VoiceCall record, a conversation is created in Salesforce. Only use this API in a real-time context, which means that you should invoke this API only when a call is initiated. This API can also be used to create VoiceCall records for transfer and conference calls by including the parentVoiceCallId parameter in the request payload.

Endpoint URI​

<instance_url>/services/apexrest/cnxscv/voice/v1/createVoiceCall

HTTP Method​

POST

Headers​

Authorization: Bearer <access_token>
Content-Type: application/json

Parameters​

{
  "callCenterDevName": "contactCenterDevName123",
  "certDevName": "certDevName123",
  "vendorCallKey": "5324881f-1e84-4367-8930-f69a74b30ca6",
  "to": "8002345678",
  "from": "4081456688",
  "initiationMethod": "Inbound",
  "startTime": "2019-07-02T17:32:28Z",
  "participants": [
    {
      "participantKey": "4081456688",
      "type" : "END_USER"
    }
  ],
  "callAttributes": "{\"devcnxscv24__AAA_Test__c\":\"field value\",\"Other_Field__c\":\"other value\"}",
  "parentVoiceCallId": "fsdfzuhsdfsa-43556fgef3-56g44gv4ew",
  "callOrigin": "Preview",
  "queue": "queue123"
}
note

A detailed description about the parameters accepted by this request can be found in the Salesforce official documentation under the "Parameters" section.

Response (successful)​

{
  "data": {
    "voiceCallId": "00X000012345abc"
  },
  "errors": null,
  "success": true
}

Response (with errors)​

{
  "data": null,
  "errors": ["Error message 1", "Error message 2"],
  "success": false
}

Update Voice Call​

Updates the VoiceCall after the call has ended. Use this API to update call-related parameters that are unavailable during the VoiceCall creation stage. The Update VoiceCall API is an asynchronous operation. You can’t query for the status of the API call.

This endpoint can also be used to create a VoiceCall even after the call has ended. This behavior is useful in scenarios where you want to log a record in Salesforce for abandoned or missed calls, or for any other scenario where a VoiceCall wasn’t already created.

Endpoint URI​

<instance_url>/services/apexrest/cnxscv/voice/v1/updateVoiceCall

HTTP Method​

POST

Headers​

Authorization: Bearer <access_token>
Content-Type: application/json

Parameters​

{
  "callCenterDevName": "contactCenterDevName123",
  "certDevName": "certDevName123",
  "voiceCallId": "00X000012345abc",
  "startTime": "2020-08-26T21:21:14Z",
  "endTime": "2019-08-26T21:21:34Z",
  "isActiveCall": true,
  "fromNumber": "1234",
  "callOrigin": "Preview",
  "enqueueTime": "2019-08-26T21:21:34Z",
  "acceptTime": "2019-08-26T21:21:24Z",
  "numberOfHolds": 20,
  "queue": "queue123",
  "agent": "agent123",
  "agentInteractionDuration": 12,
  "longestHoldDuration": 10,
  "totalHoldDuration": 21,
  "recordingLocation": "Bern",
  "totalRecordingDuration": 55,
  "callAttributes": "{\"devcnxscv24__AAA_Test__c\":\"field value\",\"Other_Field__c\":\"other value\"}",
  "disconnectReason": {
    "value": "TELECOM_PROBLEM",
    "isError": true
  }
}
note

A detailed description about the parameters accepted by this request can be found in the Salesforce official documentation under the "Parameters" section.

Response (successful)​

{
  "data": {
    "status": "pending"
  },
  "errors": null,
  "success": true
}
note

The Update VoiceCall API is an asynchronous operation. You can’t query for the status of the API call.

Response (with errors)​

{
  "data": null,
  "errors": ["Error message 1", "Error message 2"],
  "success": false
}

Execute Omni-flow​

Executes the Omni-Channel flow to route calls. It passes the call ID (Salesforce VoiceCallId or telephony vendor ContactId) as parameters to the flow and returns the agent or queue routing instructions to the contact flow. By default, Service Cloud Voice uses the Omni-Channel flow (or fallback queue) specified for the phone channel that matches the dialed number. If the dialed number doesn’t match an existing phone channel, you can optionally set a new dialed number, Omni-Channel flow, and fallback queue as input parameters to this API call.

info

Service Cloud Voice uses this order of precedence to route calls:

  1. Uses the Omni-Channel Flow and Fallback Queue settings for the phone channel that matches the dialed number. The flow takes precedence. If the flow fails, the fallback queue is used.
  2. Uses the flowDevName and fallbackQueue parameters specified in the Execute Omniflow API call.

Endpoint URI​

<instance_url>/services/apexrest/cnxscv/voice/v1/executeOmniFlow

HTTP Method​

POST

Headers​

Authorization: Bearer <access_token>
Content-Type: application/json

Parameters​

{
  "callCenterDevName": "contactCenterDevName123",
  "certDevName": "certDevName123",
  "voiceCallId": "00X000012345abc",
  "dialedNumber": "+18445791189",
  "flowDevName": "Route_VoiceCall",
  "fallbackQueue": "00G111222333444",
  "flowInputParameters":
  {
    "Input1": "one",
    "Input2": "two"
  }
}
note

The voiceCallId parameter is the Salesforce voiceCallId or the telephony vendor’s contact ID.

note

A detailed description about the parameters accepted by this request can be found in the Salesforce official documentation under the "Parameters" section.

Response (successful)​

{
  "data": {
    "queue": "queue info",
    "agent": "agent info"
  },
  "errors": null,
  "success": true
}
Note

AGENT_INFO and QUEUE_INFO correspond to the ExternalId field in the CallCenterRoutingMap

Response (with errors)​

{
  "data": null,
  "errors": ["Error message 1", "Error message 2"],
  "success": false
}

Clear routing​

Deletes the PendingServiceRouting (PSR) record for a voice call. This API doesn’t need to be called for most scenarios; the PSR record is automatically deleted when the call is no longer being routed. However, there are some scenarios, like for missed or abandoned calls when using partner telephony systems where you must explicitly call this API to clear the PSR record.

Endpoint URI​

<instance_url>/services/apexrest/cnxscv/voice/v1/clearRouting

HTTP Method​

POST

Headers​

Authorization: Bearer <access_token>
Content-Type: application/json

Parameters​

{
  "callCenterDevName": "contactCenterDevName123",
  "certDevName": "certDevName123",
  "voiceCallId": "00X000012345abc"
}
note

The voiceCallId parameter is the Salesforce voiceCallId or the telephony vendor’s contact ID.

note

A detailed description about the parameters accepted by this request can be found in the Salesforce official documentation under the "Parameters" section.

Response (successful)​

{
  "data": {
    "status": "Success"
  },
  "errors": null,
  "success": true
}

Response (with errors)​

{
  "data": null,
  "errors": ["Error message 1", "Error message 2"],
  "success": false
}

Create Transcript Message​

Create transcripts for one voice call in real time. Voice calls can include inbound calls, transfer calls, outbound calls, and callback calls. The transcript data is sent to the agent console synchronously in real time and will be persisted in Salesforce asynchronously.

note

This API creates voice call transcripts if the timestamp of the transcript is between the start and end times of the conversation, in addition it pauses call transcription whenever the agent pauses the recording or places the call participant on hold. Any messages being sent in won't be created or stored by the API during this time.

Endpoint URI​

<instance_url>/services/apexrest/cnxscv/voice/v1/createTranscriptMessage

HTTP Method​

POST

Headers​

Authorization: Bearer <access_token>
Content-Type: application/json

Parameters​

{
  "callCenterDevName": "contactCenterDevName123",
  "certDevName": "certDevName123",
  "voiceCallId": "5324881f-1e84-4367-8930-f69a74b30ca6",
  "participantId": "5324881f-1e84-4367-8930-f69a74b30ca6VIRTUAL_AGENT",
  "messageId": "57904eb6-5352-4c5e-adf6-5f100572cf5d116",
  "startTime": 1573503300000,
  "endTime": 1573503300000,
  "content": "Hello World",
  "senderType": "VIRTUAL_AGENT"
}
note

The voiceCallId parameter is the unique ID of the voice call (VoiceCall) record within the telephony system. In transfer use cases where there are multiple VoiceCall objects associated to a single call, use the vendorCallKey of the first voice call record created for the call. This value can only be the unique call identifier of the first contact for the conversation. This value can't be a Salesforce voiceCallId.

note

A detailed description about the parameters accepted by this request can be found in the Salesforce official documentation under the "Parameters" section.

Response (successful)​

{
  "data": {
    "result": "Accepted"
  },
  "errors": null,
  "success": true
}

Response (with errors)​

{
  "data": null,
  "errors": ["Error message 1", "Error message 2"],
  "success": false
}

Create Transcripts in Bulk​

Creates transcripts in bulk across multiple voice calls in real time. Voice calls can include inbound calls, transfer calls, outbound calls, and callback 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 agent console synchronously in real time and will be persisted in Salesforce asynchronously.

note

This API creates voice call transcripts if the timestamp of the transcript is between the start and end times of the conversation, in addition it pauses call transcription whenever the agent pauses the recording or places the call participant on hold. Any messages being sent in won't be created or stored by the API during this time.

Endpoint URI​

<instance_url>/services/apexrest/cnxscv/voice/v1/createBulkTranscriptMessages

HTTP Method​

POST

Headers​

Authorization: Bearer <access_token>
Content-Type: application/json

Parameters​

{
  "callCenterDevName":"contactCenterDevName123",
  "certDevName":"certDevName123",
  "entries":[
    {
      "vendorCallKey":"b09955ce-03be-4335-a28891293zs-18895",
      "messages":[
        {
          "startTime":1573503300000,
          "endTime":1573503300001,
          "participantId":"b09955ce-03be-4335-a28891293zs-18895END_USER",
          "messageId":"b09955ce-03be4335xz-a28891293zs",
          "senderType":"END_USER",
          "content":"Hello All"
        },
        {
          "startTime":1573503300002,
          "endTime":1573503300003,
          "participantId":"b09955ce-03be-4335-a28891293zs-18895VIRTUAL_AGENT",
          "messageId":"b09955ce-03be4335ej-a28891293sz",
          "senderType":"VIRTUAL_AGENT",
          "content":"Hello All"
        }
      ]
    },
    ...
  ]
}
note

The vendorCallKey is the unique ID of the voice call (VoiceCall) record within the telephony system for which messages need to be created. This value can't be a Salesforce voiceCallId.

note

A detailed description about the parameters accepted by this request can be found in the Salesforce official documentation under the "Parameters" section.

Response (successful)​

{
  "data": {
    "result": "Accepted"
  },
  "errors": null,
  "success": true
}

Response (with errors)​

{
  "data": null,
  "errors": ["Error message 1", "Error message 2"],
  "success": false
}
Last updated on