Skip to main content
Every app follows the same sequence: create one VobizClient, sign in, wait until it is registered, then make and receive calls. This page covers each step.

Create the client

Signature
Create one client for the app session and keep it, for example in your state-management layer. Call dispose() when you no longer need it.

Configuration

SdkConfig holds no credentials. Every field has a default, so const SdkConfig() works for most apps.

Logging

Pass SdkConfig(debug: true) to print log lines with debugPrint, or route them into your own logging:
Signature
Each line starts with [INFO], [WARN], or [ERROR]. Log lines can contain phone numbers and SIP usernames, so don’t upload them to third-party services without your users’ consent.

Choose a sign-in method

Every sign-in method completes once the REGISTER request is sent, not when Vobiz answers it. Watch connectionEvents for RegistrationState.registered before you place a call. Signing in again replaces the current sign-in.

SIP credentials

Signs in as an existing SIP endpoint.
Signature
Returns a Future that completes when the REGISTER is sent. Errors. If the WebSocket can’t connect, the Future throws and errorEvents emits connect_failed; with autoReconnect the SDK keeps retrying. A refused registration doesn’t throw: errorEvents emits registration_failed, and a 403 arrives with the message “Wrong credentials”.

Credentials provider

In production your backend creates one endpoint per user, keeps its password, and hands it to the app after authenticating the user with your own session. A credentials provider fetches those credentials, and fetches them again when the registrar refuses them (for example, after your backend rotated the password).
Signature
VobizCredentialsRequest tells the provider why it is called: Returns a VobizCredentialsSession: Throws VobizCredentialsException when the provider fails on the first sign-in.

Fetch credentials from your backend

VobizBackendCredentialsProvider is a ready-made provider. It sends POST <url> with the JSON body {"reason": "sign_in" | "rejected" | "refresh"} and the headers you supply, and expects:
display_name is optional. Any other field is ignored.
Signature

Access tokens

An access token is a short-lived JSON Web Token (JWT) that your backend mints for each user. The app registers with the token instead of a password, so no SIP endpoint has to exist and no long-lived secret reaches the device. Your backend mints the token with POST /api/v1/Account/{auth_id}/JWT/Token/, authenticated with your account Auth ID and Auth Token, after it has authenticated your app’s user.
Set nbf about 60 seconds in the past: a registrar clock slightly behind your server’s otherwise refuses a brand-new token with 10005 (not valid yet). Always include app.
To ring a token user, dial <User>sip:<sub>_<auth_id>@registrar.vobiz.ai</User> from your application.

Sign in with a token

Signature
The client registers as <sub>_<iss> and sends the token in an X-Vobiz-Jwt header on the REGISTER and on every outbound call. The token is not renewed: once it expires, the next REGISTER is refused with ACCESS_TOKEN_EXPIRED. Pass a fresh token to updateAccessToken before then, or use a token provider. Throws VobizAccessTokenException (INVALID_ACCESS_TOKEN, 10001) before connecting when the string isn’t a Vobiz token. A refusal by the registrar arrives on errorEvents as registration_failed, with a VobizAccessTokenException as its cause.

Token provider

A token provider signs in and keeps the sign-in alive: shortly before each token expires, the SDK asks for a new one and registers with it on the same connection, without touching a call in progress.
Signature
A token refused as not valid yet (10005) is presented again after 3 seconds instead of asking for a new one. Returns a VobizAccessTokenSession: Throws VobizAccessTokenException when the provider fails or returns something that isn’t a Vobiz token. VobizBackendAccessTokenProvider is a ready-made provider. It sends POST <url> with {"reason": "sign_in" | "expiring" | "rejected" | "refresh"} and your headers, and reads the token field of the JSON reply:

Renew a token

Signature
Presents a new token for the same user without dropping the connection or a call. Use it if you renew tokens yourself instead of using a provider. It also recovers a client whose token was refused. Throws StateError unless the client signed in with an access token, and ArgumentError when the token is for another user (a different sub or iss). To switch users, call connectWithAccessToken again.

Inspect the token

client.accessToken returns the current token as a VobizAccessToken, and client.accessTokenTimeLeft returns how long the registrar will accept it (from the registrar’s own clock).

Demo mode: Zero-Config

Zero-Config sends your account Auth ID and Auth Token from the device to a webhook server. The Auth Token is your account’s full API key. Use it only for demos and internal testing, never in a shipped app.
Signature
It works like the WebRTC Playground: the webhook server at SdkConfig.backendUrl finds or creates an application named “Vobiz WebRTC Playground” and its endpoint on your account, gives the endpoint a new password, and returns its credentials. The client then registers as that endpoint. Because the password changes on every sign-in, two devices signed in to the same account sign each other out. It requires SdkConfig(unsafeDemoZeroConfig: true) and throws VobizDemoModeRequiredException otherwise, ArgumentError when a value is empty, and VobizException (setup_failed) when the server refuses the credentials or can’t be reached. Returns a ZeroConfigSession with sipUsername, sipPassword, applicationId, message, and reusedExisting. Zero-Config is also the only mode that can transfer calls and read the recordings list.

Watch the connection

See Events and states for every event.

Sign out and clean up

Signature

Next steps