Skip to main content
Custom SIP headers carry your own data with a call: an order number, a customer ID, or an instruction for your Answer URL. Every custom header name starts with X-VH-.

How headers travel

  • App to your server. Headers you pass to makeCall go on the call’s INVITE. Vobiz passes each one to your Answer URL as a request parameter, so your VobizXML can use it.
  • Your server to the app. Headers your application sets with sipHeaders on <Dial>, <Number>, or <User> arrive on the incoming call in CallEvent.headers.

Reserved headers

X-VH-Caller-ID, X-VH-Record, and X-VH-DialUser are conventions between the app and your Answer URL. Vobiz delivers them like any other header, and your VobizXML acts on them. The hosted Playground server used in demo mode honours all three.

Rules

Leading and trailing spaces are trimmed. To send text with spaces or other characters, URL-encode it first (% is allowed).

Send headers

makeCall checks every header before dialling and throws an ArgumentError that lists every problem, for example X-VH-Customer Name: After X-VH- use 1-19 letters, digits or hyphens. Nothing is dialled until all headers are valid.

Validate a form before dialling

Validate user input before calling makeCall, for example to highlight a bad field:
Signature
The constants VobizSipHeaders.prefix (X-VH-), callerId, record, dialUser, and jwt hold the header names.

Read headers on incoming calls

Set them in your application’s VobizXML. The sipHeaders attribute takes comma-separated name=value pairs without the X-VH- prefix, which Vobiz adds:
CallEvent.headers contains only headers that pass the rules above. During the call, client.callHeaders returns the same map.

Headers in XML form

VobizSipHeaders.toXml(headers) converts headers to the value of a VobizXML sipHeaders attribute: it strips the prefix and URL-encodes each value. VobizXML allows only letters and digits in names, which is stricter than the SDK, so names with hyphens are returned in XmlSipHeaders.skipped instead of value. The demo-mode transferCall uses it.

Next steps