> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom SIP headers in the Vobiz Flutter SDK

> Send and receive X-VH- SIP headers with the Vobiz Flutter SDK: reserved headers for caller ID, recording, and dialling an endpoint, the name and value rules, validation with VobizSipHeaders, and reading headers on incoming calls.

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>`](https://www.vobiz.ai/docs/xml/dial), `<Number>`, or `<User>` arrive on the incoming call in `CallEvent.headers`.

## Reserved headers

| Header | Set by | Meaning |
| - | - | - |
| `X-VH-Caller-ID` | `makeCall(callerId:)` | The caller ID the app wants presented. Your Answer URL uses it as `<Dial callerId="...">`. |
| `X-VH-Record` | `makeCall(record: true)` | `true` asks your Answer URL to record the call. |
| `X-VH-DialUser` | `makeCall(dialUser:)` | An endpoint username your Answer URL should ring with `<Dial><User>` instead of the dialled number. |
| `X-Vobiz-JWT` | The SDK, when signed in with an access token | The access token. The only accepted header outside `X-VH-`; don't set it yourself. |

`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

| Part | Rule |
| - | - |
| Name | `X-VH-` followed by 1 to 19 letters, digits, or hyphens. For example `X-VH-OrderId`. |
| Value | 1 to 120 characters from `A-Z a-z 0-9 _ - + ( ) % .`. No spaces. |
| `X-Vobiz-JWT` value | Up to 500 characters from the same set. |
| Duplicates | Names are case-insensitive: `X-VH-Ref` and `X-VH-REF` are the same header. |

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

## Send headers

```dart theme={null}
final callId = await client.makeCall(
  '+91XXXXXXXXXX',
  callerId: '+91YYYYYYYYYY',
  headers: {
    'X-VH-OrderId': 'A1234',
    'X-VH-Lang': 'hi-IN',
  },
);
```

`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:

```dart Signature theme={null}
static Map<String, String> VobizClient.buildCallHeaders({
  Map<String, String> headers = const <String, String>{},
  String? callerId,
  bool record = false,
  String? dialUser,
})

static HeaderCheck VobizSipHeaders.check(Map<String, String> headers)
static String? VobizSipHeaders.validateName(String name)
static String? VobizSipHeaders.validateValue(String name, String value)
```

| Method | Returns |
| - | - |
| `VobizClient.buildCallHeaders` | The exact headers `makeCall` would send for these options. Throws `ArgumentError` listing every problem. |
| `VobizSipHeaders.check` | A `HeaderCheck` with `valid` (the accepted headers) and `errors` (one readable reason per rejected header). |
| `VobizSipHeaders.validateName` | Why a name is rejected, or `null` when it is valid. |
| `VobizSipHeaders.validateValue` | Why a value is rejected for that header, or `null` when it is valid. |

```dart theme={null}
void validateHeaderRow(String name, String value) {
  final nameError = VobizSipHeaders.validateName(name);
  final valueError = VobizSipHeaders.validateValue(name, value);
  if (nameError != null || valueError != null) {
    debugPrint('Fix this header: ${nameError ?? valueError}');
  }
}
```

The constants `VobizSipHeaders.prefix` (`X-VH-`), `callerId`, `record`, `dialUser`, and `jwt` hold the header names.

## Read headers on incoming calls

```dart theme={null}
void readHeaders(VobizClient client) {
  client.callEvents.listen((event) {
    if (event.state == CallStateStatus.incoming) {
      final ticket = event.headers['X-VH-Ticket'];
      debugPrint('Incoming call for ticket $ticket');
    }
  });
}
```

Set them in your application's VobizXML. The `sipHeaders` attribute takes comma-separated `name=value` pairs without the `X-VH-` prefix, which Vobiz adds:

```xml theme={null}
<Response>
  <Dial>
    <User sipHeaders="Ticket=T5678,Lang=hi-IN">sip:YOUR_SIP_USERNAME@registrar.vobiz.ai</User>
  </Dial>
</Response>
```

`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

* [Make and receive calls](https://www.vobiz.ai/docs/integrations/flutter-sdk/calls.md)
* [`<Dial>` in VobizXML](https://www.vobiz.ai/docs/xml/dial)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.