> ## 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.

# Make and receive calls with the Vobiz Flutter SDK

> Place outbound calls with makeCall, answer or decline incoming calls with acceptCall and rejectCall, hang up, and follow every call state and CallEvent field in the Vobiz Flutter SDK.

This page covers placing a call, answering and declining incoming calls, hanging up, and the states every call goes through. The client handles **one call at a time**.

## Make a call

```dart Signature theme={null}
Future<String> makeCall(
  String destination, {
  String? callerId,
  Map<String, String> headers = const <String, String>{},
  bool record = false,
  String? dialUser,
})
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `destination` | `String` | Required | The number to call, in E.164 format: `+`, the country code, then the number, such as `+91XXXXXXXXXX`. |
| `callerId` | `String?` | `null` | The caller ID you want, sent to your Answer URL as `X-VH-Caller-ID`. Your VobizXML presents it with `<Dial callerId="...">`; it must be a number your account owns. Must look like a phone number (`+` optional, 7 to 15 digits). |
| `headers` | `Map<String, String>` | `{}` | Your own `X-VH-` headers. Vobiz passes them to your Answer URL. See [Custom SIP headers](https://www.vobiz.ai/docs/integrations/flutter-sdk/sip-headers.md). |
| `record` | `bool` | `false` | Sends `X-VH-Record: true`, asking your Answer URL to record the call, for example with [`<Record>`](https://www.vobiz.ai/docs/xml/record). |
| `dialUser` | `String?` | `null` | Sends `X-VH-DialUser` with an endpoint username, asking your Answer URL to ring that endpoint with `<Dial><User>` instead of the number. Accepts `USERNAME`, `USERNAME@registrar.vobiz.ai`, or `sip:USERNAME@registrar.vobiz.ai`. A destination is still required, because it is what routes the call to your Answer URL. |

> [!NOTE]
>
> `X-VH-Caller-ID`, `X-VH-Record`, and `X-VH-DialUser` are instructions for **your Answer URL**: Vobiz delivers them, and your VobizXML acts on them. The hosted Playground server used in [demo mode](https://www.vobiz.ai/docs/integrations/flutter-sdk/sign-in.md#demo-mode-zero-config) handles all three for you.

**Returns** the SDK's ID for the call. Use it to match `CallEvent.callId`.

**Throws**

| Error | When |
| - | - |
| `StateError('No network connection')` | The device is offline. |
| `StateError` | The client isn't registered yet, or a call is already in progress. |
| `ArgumentError` | The destination is empty, the caller ID isn't a phone number, or a header is invalid. The message lists every problem, and nothing is dialled. |
| `VobizAccessTokenException` | Signed in with an access token that doesn't allow outgoing calls (`10008`). |

What happens next:

1. The SDK opens the microphone (Android asks for permission the first time), prepares audio, and sends the call to Vobiz.
2. Vobiz requests the Answer URL of the endpoint's application, with the destination in `To`. Your VobizXML decides what happens, usually a [`<Dial>`](https://www.vobiz.ai/docs/xml/dial) to the number.
3. `callEvents` reports `connecting`, then `ringing`, then `active` when the call is answered, and `ended` when it finishes.

```dart theme={null}
Future<void> callCustomer(VobizClient client) async {
  try {
    final callId = await client.makeCall(
      '+91XXXXXXXXXX',
      callerId: '+91YYYYYYYYYY',
      headers: {'X-VH-OrderId': 'A1234'},
    );
    debugPrint('Calling, call ID $callId');
  } on ArgumentError catch (e) {
    debugPrint('Fix these before dialling: ${e.message}');
  } on StateError catch (e) {
    debugPrint('Cannot call now: ${e.message}');
  }
}
```

> [!NOTE]
>
> Placing a call spends money on your Vobiz account. Test with your own numbers.

### Caller ID

Carriers reach a phone only when the caller ID is a number your Vobiz account owns. Your Answer URL sets it with `<Dial callerId="...">`; pass `callerId` to `makeCall` if the app chooses the number, and read it from the `X-VH-Caller-ID` parameter on your server. A call without a valid caller ID fails, and `callEvents` reports `failed` with the SIP code.

### Ringing and early media

When the far end sends `183 Session Progress` with audio, such as ringback or a carrier announcement, the SDK plays it before the call is answered and emits an `EarlyMediaEvent` on `callMediaEvents`.

If Vobiz sends no response at all within 30 seconds, the call ends with reason `setup_timeout`. Once the destination is ringing, the call keeps ringing until it is answered, declined, or times out on the Vobiz side.

## Receive a call

A call rings the app when:

* your application's VobizXML rings the endpoint with `<Dial><User>sip:YOUR_SIP_USERNAME@registrar.vobiz.ai</User></Dial>`, or
* you place a call to `sip:YOUR_SIP_USERNAME@registrar.vobiz.ai` with the [Voice API](https://www.vobiz.ai/docs/call/make-call.md).

The client must be signed in and registered (on Android with the app closed, see [Push notifications](https://www.vobiz.ai/docs/integrations/flutter-sdk/push-notifications.md)). When the call arrives, `callEvents` emits a `CallEvent` with `state: CallStateStatus.incoming`.

```dart theme={null}
void listenForCalls(VobizClient client) {
  client.callEvents.listen((event) {
    if (event.state != CallStateStatus.incoming) return;
    final caller = event.remoteIdentity ?? 'Unknown caller';
    final orderId = event.headers['X-VH-OrderId'];
    debugPrint('Incoming call from $caller (order $orderId)');
    // Show your ringing UI, then call acceptCall or rejectCall.
  });
}
```

| Field | Description |
| - | - |
| `remoteIdentity` | The caller's number or SIP user, taken from `P-Asserted-Identity`, `Remote-Party-ID`, `From`, or `Contact`. |
| `headers` | The `X-VH-` headers on the INVITE, such as those your application set with `<User sipHeaders="...">`. |
| `callUuid` | Vobiz's CallUUID for this leg (`X-Calluuid`). |
| `sipCallId` | The INVITE's SIP Call-ID. |

While a call is in progress, a second incoming call is declined with `486 Busy Here`: the caller hears busy and the app isn't disturbed.

### Answer

```dart Signature theme={null}
Future<void> acceptCall([String? callId])
```

Answers the ringing call. `callId` defaults to the current call. It does nothing unless the call is `incoming`. The state moves to `connecting` ("Answering"), then `active`.

If answering fails, the SDK declines the call so the caller isn't left ringing: `480` when the microphone can't be opened, `488` when the offer has no usable audio, and `500` otherwise. `errorEvents` emits `answer_failed`.

```dart theme={null}
await client.acceptCall();
```

### Decline

```dart Signature theme={null}
Future<void> rejectCall([String? callId])
```

Declines a ringing call with `486 Busy Here`: the caller hears busy. On a call that is already answered, it hangs up instead.

```dart theme={null}
await client.rejectCall();
```

If the caller hangs up before you answer, the call ends with the reason `Caller cancelled`.

## Hang up

```dart Signature theme={null}
Future<void> hangup([String? callId])
```

Ends the call. A ringing outbound call is cancelled (`CANCEL`), an incoming call that is still ringing is declined, and an answered call gets a `BYE`. Both sides see the call end. `callId` defaults to the current call; with no call, it does nothing.

```dart theme={null}
await client.hangup();
```

If the network is down when you hang up, the SDK sends the `BYE` or `CANCEL` again once it reconnects, so the other side isn't left on a silent call. See [Network and reconnection](https://www.vobiz.ai/docs/integrations/flutter-sdk/network.md#calls-during-a-network-drop).

## Call states

`CallEvent.state` is a `CallStateStatus`:

| State | Meaning |
| - | - |
| `connecting` | An outbound call is being prepared, or an incoming call is being answered. |
| `ringing` | The call was sent. Also re-emitted as the far end reports progress ("Remote ringing", "Call progress"). |
| `incoming` | A call is ringing this app. |
| `active` | The call is connected. |
| `held` | You put the call on hold. |
| `failed` | The call couldn't connect. `sipCode` and `reason` say why. Always followed by `ended`. |
| `ended` | The call is over. `reason` says why. |
| `idle` | No call. Returned by `client.callState` between calls; not emitted as an event. |
| `outgoing` | Reserved; not emitted. |

**Outbound sequence:** `connecting` > `ringing` > `active` > (`held` > `active`) > `ended`.
**Inbound sequence:** `incoming` > `connecting` > `active` > `ended`.

During a network drop, the SDK re-emits the current state with `reason` set to `reconnecting`, then `reconnected` when the call recovers.

### Why a call ended

| `reason` | Meaning |
| - | - |
| `Hung up` | You hung up. |
| `Rejected` | You declined the incoming call. |
| `Caller cancelled` | The caller hung up before you answered. |
| `setup_timeout` | Vobiz didn't answer the call request within 30 seconds. |
| `network_lost` | The network dropped and didn't come back within 12 seconds, or dropped while the call was being set up. |
| `answer_failed` | The call couldn't be answered, or the far end's answer couldn't be used. |
| `disconnected` | You signed out during the call. |
| Other text | The far end's reason, as specific as it reported it, such as `USER_BUSY (Q.850 17)`. |

## CallEvent

| Field | Type | Description |
| - | - | - |
| `callId` | `String` | The SDK's ID for the call. Returned by `makeCall`. |
| `state` | `CallStateStatus` | The new state. |
| `direction` | `CallDirection?` | `inbound` or `outbound`. |
| `remoteIdentity` | `String?` | The number or SIP user on the other end. |
| `callUuid` | `String?` | Vobiz's CallUUID for this leg, once known. Needed to transfer a call and to find its recording. |
| `headers` | `Map<String, String>` | The `X-VH-` headers you sent, or that arrived on an incoming call. |
| `sipCode` | `int?` | The SIP status code when a call fails, such as `486` or `603`. |
| `reason` | `String?` | Why the call failed or ended. |
| `message` | `String?` | A human-readable description of the event. |
| `sipCallId` | `String?` | The SIP Call-ID. |
| `timestamp` | `DateTime` | When the event happened. |

The client also exposes the current call's state directly: `callState`, `currentCallId`, `callDirection`, `callUuid`, `lastCallUuid` (the previous call's, for recordings), and `callHeaders`.

## Next steps

* [In-call controls](https://www.vobiz.ai/docs/integrations/flutter-sdk/in-call-controls.md)
* [Custom SIP headers](https://www.vobiz.ai/docs/integrations/flutter-sdk/sip-headers.md)
* [Push notifications](https://www.vobiz.ai/docs/integrations/flutter-sdk/push-notifications.md)


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