Missing custom headers

Question

Good evening everyone,

we are developing a simple solution for outbound calling some phone numbers, playing a simple message (alerting in case of emergencies) and hung up the call.

I have seen that in the documentation of the Javascript SDK for call automation there is, in the CallInvite Object (CallInvite reference page), a property named "customCallingContext" to add custom SIP headers to the INVITE (CustomCallingContext reference page and SipCustomHeader reference page).

Unfortunately populating those in the following way:

const acsCallID = generateUUID();
const customCallingContext: CustomCallingContext = [];
customCallingContext.push({
	kind: "sipuui",
	key: "",
	value: acsCallID
})
customCallingContext.push({
	kind: "sipx",
	key: "acsCorrelationID",
	value: acsCallID
})
const callInvite : CallInvite = {
	targetParticipant: callee,
	sourceCallIdNumber: callerID,
	customCallingContext
};


const callCreationOptions: CreateCallOptions = { callIntelligenceOptions: { cognitiveServicesEndpoint: process.env.COGNITIVE_SERVICES_ENDPOINT } };
acsClient.createCall(callInvite, callbackURI + "/api/callbacks", callCreationOptions)

I do not receive the custom header in the SIP Invite message on the SBC.

The implementation seems correct to me.

Have anyone dealt with the same issue?

Thank you in advance

Best regards

Answer 1

@Davide Rasoli Thank you for bringing this to our attention.

After checking with our Product Group, they have confirmed that the public documentation can indeed be misleading in this case — and we sincerely apologize for any confusion this has caused.

We will be taking action to update and clarify the documentation to better reflect the current capabilities.

Regarding your specific issue: at this time, the Create Call API does not yet support custom context, which is why you are encountering this limitation.

We truly appreciate you raising this. It has helped us identify a gap, and we’ve added your feedback to our product roadmap to prioritize support for this feature in the future.

Answer 2

Hi Davide Rasoli,

In the above code , we are treating customCallingContext as an array, but it should be an object with a sipHeaders property, and sipHeaders is an array of { name, value } pairs. Also, the keys like "kind": "sipuui" and "kind": "sipx" don’t apply here — they come from a different SDK (CallAutomationCustomCallingContext in C#/.NET) or are possibly part of legacy/internal formats, but not for the JavaScript SDK.

1. Ensure you're using Direct Routing with an SBC: Custom SIP headers are only delivered when the call is routed via Direct Routing to an SBC. They will not survive if the call routes to a normal PSTN number via Azure’s carrier backbone.
2. Check SBC logs: Confirm that the INVITE received at your SBC actually does not contain X-acsCorrelationID. Some SBCs (like AudioCodes) may suppress headers unless explicitly allowed.
3. Use a SIP trace tool: Use something like sngrep, Wireshark, or built-in SBC tools to view SIP INVITE headers. Look for X-acsCorrelationID: {value}.
4. Header name must start with X-: SIP spec requires custom headers to be prefixed with X-. Names like acsCorrelationID (without X-) may be dropped or ignored.

Please refer- https://learn.microsoft.com/en-us/azure/communication-services/how-tos/call-automation/custom-context?tabs=csharp

just an Example to define customCallingContext:

import { CallInvite, CustomCallingContext, SipCustomHeader } from "@azure/communication-call-automation"; // or similar depending on your setup
const acsCallID = generateUUID();
const customCallingContext: CustomCallingContext = {
  sipHeaders: [
    {
      name: "X-acsCorrelationID",
      value: acsCallID
    }
  ]
};
const callInvite: CallInvite = {
  targetParticipant: callee,
  sourceCallIdNumber: callerID,
  customCallingContext
};
const callCreationOptions: CreateCallOptions = {
  callIntelligenceOptions: {
    cognitiveServicesEndpoint: process.env.COGNITIVE_SERVICES_ENDPOINT
  }
};
acsClient.createCall(callInvite, callbackURI + "/api/callbacks", callCreationOptions);

If you have any further assistant, do let me know.