Create Voice Call Context

Allocates a server-minted contextID handle for a voice call transfer to Agentforce Voice.

Use this API to obtain a contextID 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 contextID in a SIP X-header on the outbound SIP-address transfer leg. Salesforce’s SIP relay looks up the stored call context by this contextID at ringing time and hands the call off to Agentforce Voice with the correct session context. The returned contextID 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 contextID 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
`countryCode`	string	ISO 3166-1 alpha-2 country code of the destination. For example, `US`.	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 contextID lease isn’t created.	No
`additionalParams`	object<string,string>	Free-form key/value parameters reserved for future use.	No

The contextID 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 `contextID` for this endpoint.
`handle`	object	The reserved handle (`VoiceCallContextHandle`). See handle (VoiceCallContextHandle).

handle (VoiceCallContextHandle)

Property Name	Type	Description
`contextID`	string	Server-minted UUIDv4 context 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  "countryCode": "US",
6  "context": {
7    "scrt2Domain": "https://example.my.salesforce-scrt.com",
8    "toNumber": "+15551234567",
9    "callId": "0LQxx0000004ABcGAM",
10    "partnerCallId": "vendor-call-abc-123",
11    "transactionId": "8f3c9e2a-1b4d-4e7f-9a0c-2d6e1f3b5a8c",
12    "additionalParams": {
13      "key1": "value1"
14    }
15  }
16}

Response:

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