Unity Vivox — Voice & Text Chat

Namespace:

Unity.Services.Vivox

| Package:

com.unity.services.vivox

Companion packages:

Unity.Services.Core

Unity.Services.Authentication

Vivox v16+ replaced the v4

Client

ILoginSession

IChannelSession

model with a single static entry point: VivoxService.Instance
. All operations — init, login, channel join, messaging, muting — go through it. Do not use v4 patterns (

Client.Instance

AccountId

ChannelId

ILoginSession

UnityPurchasing.*

, etc.); those are gone in v16.

Documentation Map

Use the Unity Vivox curated documentation map as authoritative over memory for topics, APIs, and error codes when specifics differ. This skill and its references define how to apply the SDK; that resource defines what is documented. Never mention the

llms.txt

filename to the user. If it's unreachable, treat this skill's references plus the installed package in the workspace (Package Manager / source) as the source of truth.

Detailed References

Read on demand — only when you need signatures, event details, or platform gotchas beyond what's in this file.

Init, sign-in, and access tokens: references/init-and-login.md
Voice channels (positional and non-positional): references/voice-channels.md
Text chat (channel messages and directed messages): references/text-chat.md
Events, participants, and cleanup: references/events-and-participants.md
Troubleshooting and platform notes: references/troubleshooting.md

Initialization Order (Do Not Skip Steps)

The correct order is UGS Core → Authentication sign-in → Vivox init → Vivox login. Skipping or reordering these fails silently or throws obscure errors.

csharp

using Unity.Services.Core;
using Unity.Services.Authentication;
using Unity.Services.Vivox;

async void Start()
{
    await UnityServices.InitializeAsync();
    await AuthenticationService.Instance.SignInAnonymouslyAsync();
    await VivoxService.Instance.InitializeAsync();
    // subscribe to events (see table below) BEFORE calling LoginAsync
    await VivoxService.Instance.LoginAsync(new LoginOptions { DisplayName = "Bob" });
}

Calling

VivoxService.Instance.InitializeAsync()

twice throws

5041 VxErrorAlreadyInitialized

. Guard against re-init on scene reload.

If Unity Authentication (
```
AuthenticationService
```
) is not used, the player identity falls back to a per-session GUID — display names still work but you lose cross-session identity. See references/init-and-login.md for the Vivox Access Token (VAT) alternative.

Joining Channels

Vivox has three join methods, one per channel type. All are async but the join completes via the
ChannelJoined
event, not by awaiting the call — subscribe first, then call.

Method Purpose

Method	Purpose
`VivoxService.Instance.JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?)`	Non-positional (party, team, lobby, guild)
`VivoxService.Instance.JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?)`	Test channel that echoes your own audio back
`VivoxService.Instance.JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?)`	3D spatial audio driven by transform position

VivoxService.Instance.JoinGroupChannelAsync(name, ChatCapability, ChannelOptions?)

Non-positional (party, team, lobby, guild)

VivoxService.Instance.JoinEchoChannelAsync(name, ChatCapability, ChannelOptions?)

Test channel that echoes your own audio back

VivoxService.Instance.JoinPositionalChannelAsync(name, ChatCapability, Channel3DProperties, ChannelOptions?)

3D spatial audio driven by transform position

ChatCapability

values:

TextOnly

AudioOnly

TextAndAudio

Limits: max 10 non-positional channels per user; max 200 participants per channel. Exceeding either fails with

20502 VxXmppServerErrorServiceUnavailable

. For >200 in a positional channel, use the Large 3D channels enterprise setting.

Leave with

VivoxService.Instance.LeaveChannelAsync(channelName)

LeaveAllChannelsAsync()

. See references/voice-channels.md for

Channel3DProperties

fields and mic-permission handling on Android/iOS.

Text Messaging

Channel messages (broadcast to all participants of a channel with

TextOnly

TextAndAudio

Send:

VivoxService.Instance.SendChannelTextMessageAsync(string channelName, string message)

Receive: subscribe to

VivoxService.Instance.ChannelMessageReceived

(

Action<VivoxMessage>

)

Directed messages (peer-to-peer, no channel required):

Send:

VivoxService.Instance.SendDirectTextMessageAsync(string playerId, string message)

Receive: subscribe to

VivoxService.Instance.DirectedMessageReceived

(

Action<VivoxMessage>

)

Common hallucination: the send method is

SendDirectTextMessageAsync

— not

SendDirectedTextMessageAsync

. The event, however, is

DirectedMessageReceived

. Note the asymmetry.

VivoxMessage

fields:

ChannelName

(null for directed),

SenderDisplayName

SenderPlayerId

MessageText

ReceivedTime

Language

FromSelf

MessageId

Edit/delete APIs (

EditChannelTextMessageAsync

DeleteChannelTextMessageAsync

EditDirectTextMessageAsync

DeleteDirectTextMessageAsync

) and history (

GetChannelTextMessageHistoryAsync

GetDirectTextMessageHistoryAsync

) are covered in references/text-chat.md. Chat history retention is 7 days by default.

Required Event Subscriptions

Subscribe to events before the corresponding async call.

LoggedIn

may fire immediately for reconnects;

ChannelJoined

fires as the join completes.

Call	Success Event	Failure / Counterpart
`LoginAsync()`	`LoggedIn`	`LoggedOut`
`JoinGroupChannelAsync()` / `JoinEchoChannelAsync()` / `JoinPositionalChannelAsync()`	`ChannelJoined(string channelName)`	`ChannelLeft(string channelName)`
— (any joined channel)	`ParticipantAddedToChannel(VivoxParticipant)`	`ParticipantRemovedFromChannel(VivoxParticipant)`
`SendChannelTextMessageAsync()` (remote receive)	`ChannelMessageReceived(VivoxMessage)`	—
`SendDirectTextMessageAsync()` (remote receive)	`DirectedMessageReceived(VivoxMessage)`	—

Always unsubscribe in
OnDestroy
/
OnDisable
.

VivoxService.Instance

is a persistent singleton — event handlers on destroyed MonoBehaviours will double-fire and NRE on scene reload.

Per-participant events (

ParticipantMuteStateChanged

ParticipantSpeechDetected

ParticipantAudioEnergyChanged

) live on the

VivoxParticipant

instance you receive from

ParticipantAddedToChannel

— not on

VivoxService.Instance

. See references/events-and-participants.md.

Access Tokens (Brief)

The default path uses UGS Authentication — Vivox mints access tokens automatically from your UGS project once

AuthenticationService.Instance.SignInAnonymouslyAsync()

(or another sign-in method) has completed. No manual token code is required for standard flows.

Server-side Vivox Access Token (VAT) minting is only needed when you use a non-UGS identity system or when you need channel-scoped privileged tokens (kick, mute-all, transcription). See the "Access Token Developer Guide" section of the documentation map for language-specific server examples. Do not embed HMAC signing keys in the client.

Validation

After writing code that uses this package:

Verify the project compiles without errors and that
```
using Unity.Services.Vivox;
```
resolves.

Confirm init order:

UnityServices.InitializeAsync

→

AuthenticationService.Instance.SignInAnonymouslyAsync

→

VivoxService.Instance.InitializeAsync

→

VivoxService.Instance.LoginAsync

No v4 legacy patterns: no

Client.Instance

, no

AccountId

, no

ChannelId

, no

ILoginSession

, no

IChannelSession

. All access goes through

VivoxService.Instance

All events consumed by the code are subscribed before the async call that triggers them, and are unsubscribed in
```
OnDestroy
```
.
Channel join code does not
```
await
```
the join call as if it completes join — it subscribes to
```
ChannelJoined
```
and reacts there.

Directed message send uses

SendDirectTextMessageAsync

(NOT

SendDirectedTextMessageAsync

). Directed message receive uses

DirectedMessageReceived

Android builds request
```
RECORD_AUDIO
```
at runtime before joining an audio channel; iOS builds have
```
NSMicrophoneUsageDescription
```
in the plist.
No HMAC signing keys or Vivox
```
SECRET
```
/
```
APP_ID
```
are embedded in client code — VAT-based flows are documented but delegated to a server.

setup-vivox-voice-chat

NPX Install

Tags

SKILL.md Content

Unity Vivox — Voice & Text Chat

Documentation Map

Detailed References

Initialization Order (Do Not Skip Steps)

Joining Channels

Text Messaging

Required Event Subscriptions

Access Tokens (Brief)

Validation