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
PassSdkConfig(debug: true) to print log lines with debugPrint, or route them into your own logging:
Signature
[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 withPOST /api/v1/Account/{auth_id}/JWT/Token/, authenticated with your account Auth ID and Auth Token, after it has authenticated your app’s user.
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
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
Signature
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