Call Headers

Call Headers can be used to pass custom data from a Sinch SDK client to another, or specified in an ICE response to be made available to the receiving client. Further, if Call Headers is specified they will be available in ICE and DICE events.

Example use cases:

  • Specify call headers at call initiation in end-user application (via Sinch SDK client) to make them available to callee client.
  • Specify call headers in ICE response to make them available to callee client.

Specifying Call Headers in Sinch SDK Clients (iOS & Android)

If the custom data is available with the initiating client and you want to make it available to the receiving client and in ICE and DICE events, pass call headers when initiating the calls using the following Sinch SDK APIs:

  • Android: userId, Map<String,String> headers)
  • iOS: -[SINCallClient callUserWithId:headers:]

This will make the call headers available in ICE and DICE events (as callHeaders), and on the call objects in the Sinch SDKs (Call.headers on Android, -[SINCall headers] on iOS).

Specifying Call Headers in ICE response

You can provide call headers in the ICE response as part of an action, example connectMXP. This will make the call headers available to the callee client and in the DICE event.

Example of ICE response:

  "action": {
    "name": "connectMXP",
    "callHeaders": [
      { "key": "foo", "value": "bar" },
      { "key": "baz", "value": "qux" }

The maximum size for the value of call headers is 1024 bytes (counted as the UTF-8 encoded size of each header key/value pair).


When call headers are specified in an ICE response, they will be made available to the callee, but not to the caller. If the call headers were specified first by caller client, but then overriden via ICE response, the caller won't be updated of the changed call headers.

Call Headers and the custom Field

WARNING: This is a deprecated feature.

The ICE and DICE events have a field named custom. If call headers are specified at call initation on SDK client or via ICE response, the call headers will be available in custom in a JSON encoded format. example if a call is initiated with headers {"foo": "x"} then the value of custom will be "{\"foo\":\"x\"}".

Note that call headers are only mapped to custom for Sinch SDK client calls and it's considered a legacy feature. It's strongly recommended to use callHeaders as specify/override call headers in ICE and DICE.


The value type of custom is always a string and the JSON-encoded representation of headers will be escaped when the string value is part of the larger ICE event structure. From the perspective of the structure of the ICE-event, the value of custom is just an opaque string.

The maximum size for the value of custom is 1024 bytes.

We'd love to hear from you!
Rate this content:
Still have a question?
Ask the community.