Skip to content
Voice/
/
Call headers
Sinch Voice API: Choosing between v1 and v2

For all new projects, please use Voice API v2. This is especially important for projects involving:

  • AI capabilities like Streams and Voice Relay
  • Voice campaigns like Batch calling

You should only use the older Voice API v1 if one of the following is a strict requirement:

  • The project must be in General Availability (GA).
  • The project requires In-App voice or Conferencing (until these features are available in v2).

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: CallClient.call(String 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).

Important!

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.

Important!

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.

Get a second number

Callbacks