Create Voice Call Context | Salesforce Voice with Telephony Providers Implementation Guide

Use this API to obtain a correlation-id handle before performing a SIP-address transfer of the PSTN call to Salesforce. The partner telephony system calls this API to reserve the context, then places the returned correlationId in a SIP X-header on the outbound SIP-address transfer leg. Salesforce's SIP relay looks up the stored call context by this correlation-id at ringing time and hands the call off to Agentforce Voice with the correct session context. The returned correlationId is valid for a limited time and can't be supplied by the client—the value is always server-minted. This API is available only to organizations provisioned for Agentforce Voice with the correlation-id transfer mode enabled.

URI

https://{MyDomain}.my.salesforce-scrt.com/telephony/v1/voiceCalls/createVoiceCallContext

Where {MyDomain} is a value configured as part of Salesforce setup.

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

The request body is CreateVoiceCallContextRequest.

Property Name	Type	Description	Required
`fromNumber`	string	The caller's phone number in E.164 format. For example, `+14155551234`. This number is used for validation during call lookup.	Yes
`context`	object	The voice-call context (`VoiceCallContext`) associated with this reservation. See context (VoiceCallContext).	Yes

context (VoiceCallContext)

Property Name	Type	Description	Required
`scrt2Domain`	string	The SCRT2 domain URL for the Salesforce organization. For example, `https://example.my.salesforce-scrt.com`.	Yes
`toNumber`	string	The virtual phone number in E.164 format that you configure in Salesforce.	Yes
`callId`	string	The ID of the initial voice call record (VC1) that's created when the inbound call to the partner contact center. If omitted, context chaining with the parent voice call doesn't happen.	No
`partnerCallId`	string	Vendor call key or UUID for the originating call leg. Reserved for phase 2.	No
`transactionId`	string	A UUID that uniquely identifies this `createVoiceCallContext` request. If provided, Salesforce uses this value to support idempotent retry behavior. If the partner contact center retries the request due to a timeout or transient error, passing the same `transactionId` ensures that a duplicate correlation-id lease isn't created.	No
`additionalParams`	object<string,string>	Free-form key/value parameters reserved for future use.	No

The correlationId can't be supplied by the client. The server always mints a new UUIDv4 and returns it in the response.

Note

Response

The response body is CreateVoiceCallContextResponse.

Property Name	Type	Description
`status`	string	Outcome of the context reservation. One of `success` or `failure`.
`mode`	string	Mode of the reserved handle. Always `correlationID` for this endpoint.
`handle`	object	The reserved handle (`VoiceCallContextHandle`). See handle (VoiceCallContextHandle).

handle (VoiceCallContextHandle)

Property Name	Type	Description
`correlationId`	string	Server-minted UUIDv4 correlation identifier. Place this value in the SIP X-header on the SIP-address transfer leg.
`expiresAt`	string	ISO-8601 timestamp at which the lease expires.

Example

Request:

1POST /telephony/v1/voiceCalls/createVoiceCallContext
2
3{
4  "fromNumber": "+14155551234",
5  "context": {
6    "scrt2Domain": "https://example.my.salesforce-scrt.com",
7    "toNumber": "+15551234567",
8    "callId": "0LQxx0000004ABcGAM",
9    "partnerCallId": "vendor-call-abc-123",
10    "transactionId": "8f3c9e2a-1b4d-4e7f-9a0c-2d6e1f3b5a8c",
11    "additionalParams": {
12      "key1": "value1"
13    }
14  }
15}

Response:

1{
2  "status": "success",
3  "mode": "correlationID",
4  "handle": {
5    "correlationId": "a3f2c4d8-9b7e-4c6f-8e1d-2f5a9c3b7e4d",
6    "expiresAt": "2026-05-22T18:45:11Z"
7  }
8}