The official Unity SDK for Stream Chat.

Website | Tutorial | SDK Documentation | Register for API Key

---

The Stream Chat SDK is the official Unity SDK for Stream Chat, a service for building chat and messaging games and applications.

• Unity Engine 6, 2023.x, 2022.x, 2021.x, 2020.x, and 2019.x Support
• IL2CPP Support
• Automatic State Management The Chat Client completely manages the state. You work with high-level models that simplify API interaction and are always up-to-date
• Automatic Reconnection Whenever the connection is lost, the chat client will reconnect automatically when the network is back
• Realtime Highly responsive experience using Websockets
• Messaging: Send direct or group messages, and have the messages persist across sessions
• Channels: group channels, private messages, etc.
• Reactions: Multiple users can react to every message, custom reactions
• Moderation: Banning (temporary, permanent, shadow), Muting (users, channels), Flagging (messages, users)
• Roles & Permissions: Admins, Moderators, custom roles with custom permission
• Moderation Dashboard Dedicated web panel to handle moderation
• Search Search through message history
• Unread counts Show the last read message per user and count unread messages
• Typing indicators See who's currently writing a new message
• Fully open-source: Complete access to the SDK source code here on GitHub

IL2CPP

IL2CPP is supported 🚀

WebGL

WebGL is supported 🚀

Free for Indie Developers

Stream is free for most side and hobby projects. You can use Stream Chat for free with less than five team members and no more than $10,000 in monthly revenue. Visit our website and apply for the Makers Account.

Getting Started

1. Download the latest release .unitypackage.
2. Launch Unity Editor and import the downloaded .unitypackage
3. Resolve dependencies
4. Start integrating Chat into your project! Check out the Tutorial to get yourself going.

Tutorial

Check out our tutorial on how to setup your project and perform basic operations.

Sample Project

In the StreamChat/SampleProject folder you'll find a fully working chat example featuring:

• Browsing channels and messages
• Sending, Editing, Deleting messaged
• Message right-click context menu
• Reactions/Emojis
• Member list with online status
• Typing indicators
• Moderation: flagging messages and users
• Sending video attachments (works only in Editor)

Preview

Created with Unity's UGUI UI system and supports both legacy and the new Unity's Input System.

How to run it?

1. Register an account and go to Stream Dasboard
2. Create App and go to its Chat Explorer throught the Dashboard
3. Create new chat user and save its id
4. Use our online token generator to create user token
5. In Unity, provide: Api Key, User Id and User Token into StreamChat/SampleProject/Config/DemoCredentials.asset
6. Open StreamChat/SampleProject/Scenes/ChatDemo.scene and hit play

How to enable Unity's new Input System?:

1. Make sure that the UnityEngine.InputSystem package is available in the project
2. Add UnityEngine.InputSystem dll reference to the StreamChat.Unity assembly definition asset

Dependencies

• TextMeshPro StreamChat/SampleProject requires a TextMeshPro package
• Newtonsoft.Json SDK uses Unity's package for Newtonsoft Json Library for serialization.

⚠️ In case you already have the Newtonsoft Json dll or package in your project and encounter the following error:
Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included or the current platform. Only one assembly with the same name is allowed per platform.
you can remove the StreamChat\Libs\Serialization\com.unity.nuget.newtonsoft-json@3.0.2 directory. Please note however, that Unity's package for Newtonsoft Json has IL2CPP support. If you wish to replace it and still use IL2CPP, make sure that the Json implementaion of your choice does support IL2CPP as well.

Short Documentation (Cookbook)

Here are some quick Code Samples to get you started. For detailed information please check out our Documentation

Vocabulary:

• StreamChatClient - the main chat manager that allows you to connect with the Stream Chat Server, create channels, query channels, users, and members based on provided criteria
• StreamChannel - channels group users in a conversation. Depending on your settings users may need to join channels as members in order to send messages
• StreamUser - represent a single user within your application
• StreamChannelMember - object representing a user that is a member of a specific channel. This object contains property member.User to access the user object
• StreamMessage - represents a single message within a channel

Create an instance of chat client

User the StreamChatClient.CreateDefaultClient(); factory method to create an instance of IStreamChatClient:

publicclassChatManager:MonoBehaviour{publicIStreamChatClientClient{get;privateset;}protectedvoidAwake(){Client=StreamChatClient.CreateDefaultClient();}}

Connect the user

Easiest way to start is to enable developer authorization and connect with client-side generated auth tokens:

varuserId=StreamChatClient.SanitizeUserId("user-name");varuserToken=StreamChatClient.CreateDeveloperAuthToken(userId);// Replace API_KEY with your Api Key from the Stream DashboardvarlocalUserData=awaitClient.ConnectUserAsync("API_KEY",userId,userToken);

Async or Callback

Every function that waits for response from the server you can either call using the C# modern async/await syntax or append the .AsCallback() and use as classical callbacks as follows:

Client.ConnectUserAsync("API_KEY",userId,userToken).AsCallback(onSuccess: result =>{varlocalUserData=result;},onFailure: exception =>{Debug.LogException(exception);});

The .AsCallback() method accepts two delegates: Action<TResponse> onSuccess and the Action<Exception> onFailure that you can use to react to both successfull and error response case. Instead lambda callbacks you can also provide methods with the same signature as in the example below:

publicvoidConnectUser(){varuserId=StreamChatClient.SanitizeUserId("user-name");varuserToken=StreamChatClient.CreateDeveloperAuthToken(userId);Client.ConnectUserAsync("API_KEY",userId,userToken).AsCallback(OnUserConnected,OnUserConnectionFailed);}privatevoidOnUserConnected(IStreamLocalUserDatalocalUserData){Debug.Log("User connected: "+localUserData.User.Name);}privatevoidOnUserConnectionFailed(Exceptionexception){Debug.LogException(exception);}

We strongly advice using the async/await syntax which, as you'll notice in the following examples, makes the code much simpler and easier to read and maintain.

Create a channel

Once you're connected you can start using channels so that users can send messages.

There are 2 ways to create channels:

1. By ID

For predefined channels to which users can join. This is great for any general purpose channels or clans, clubs, groups which users can join or leave.

varchannel=awaitClient.GetOrCreateChannelWithIdAsync(ChannelType.Messaging,"my-channel-id");

or with a callback:

Client.GetOrCreateChannelWithIdAsync(ChannelType.Messaging,"my-channel-id").AsCallback(channel =>{Debug.Log($"Channel {channel.Id} created successfully");}, exception =>{Debug.LogException(exception);});

2. For a group of users

Great for public or private group messages, the order of users in group doesn't matter so whenever the users are connected using this method they will always see their chat history:

varchannel=awaitClient.GetOrCreateChannelWithMembersAsync(ChannelType.Messaging,users);

Query Channels

To browse all channels or channels filtered by some criteria use Client.QueryChannelsAsync

Query channels to which local user belongs as a member

varfilters=newIFieldFilterRule[]{ChannelFilter.Cid.In("channel-cid","channel-2-cid","channel-3-cid")};varsort=ChannelSort.OrderByAscending(ChannelSortFieldName.CreatedAt);varchannels=awaitClient.QueryChannelsAsync(filters,sort);

The filtering mechanism is very powerful and allows you to combine multiple rules. You can check the full list of available fields and operators that you can use for channel querying here.

Channel Filters Examples:

Filter for channels with Cid

// Each operator usually supports multiple argument types to match your needsChannelFilter.Cid.EqualsTo("channel-cid");// stringChannelFilter.Cid.EqualsTo(channel);// IStreamChannelChannelFilter.Cid.In("channel-cid","channel-2-cid","channel-3-cid");// Comma separated stringsvarchannelCids=newList<string>{"channel-1-cid","channel-2-cid"};ChannelFilter.Cid.In(channelCids);// Any collection of string

Filter for channels created by the local user

varfilters=newIFieldFilterRule[]{ChannelFilter.CreatedById.EqualsTo(Client.LocalUserData.User)};

Filter for channels with more than 10 members

varfilters=newIFieldFilterRule[]{ChannelFilter.MembersCount.GreaterThan(10)};

Filter for channels created last week

varweekAgo=DateTime.Now.AddDays(-7).Date;varfilters=newIFieldFilterRule[]{ChannelFilter.CreatedAt.GreaterThan(weekAgo)};

Filter for channels updated within last 24 hours

vardayAgo=DateTime.Now.AddHours(-24);varfilters=newIFieldFilterRule[]{ChannelFilter.UpdatedAt.GreaterThan(dayAgo)};

Get messages

Messages are accessible via channel.Messages property that contains collection of the most recent messages. Because there can potentialy be thousands of messages in a channel history the channel.Messages collection contains only the latest messages. You can load older messages by calling the channel.LoadOlderMessagesAsync() which will load additional portion of the history. A common approach is to call channel.LoadOlderMessagesAsync() whenever users hits the end of your messages scroll view, this way you only load older messages when the user actually wants to view them. You can see an example of this approach in Sample Project's MessageListView.cs

Send message

varsentMessage=awaitchannel.SendNewMessageAsync("Hello");

Send message to a thread

varmessageInThread=awaitchannel.SendNewMessageAsync(newStreamSendMessageRequest{ParentId=parentMessage.Id,// Write in threadShowInChannel=false,// Optionally send to both thread and the main channel like in SlackText="Hello",});

Quote a message

varmessageWithQuote=awaitchannel.SendNewMessageAsync(newStreamSendMessageRequest{QuotedMessage=quotedMessage,// Reference to IStreamMessage Text="Hello",});

Silent message

Silent messages do not trigger events for channel members. Often used for system messages

varsilentMessage=awaitchannel.SendNewMessageAsync(newStreamSendMessageRequest{Text="System message",Silent=true});

Pin message

Pin indefinitely

awaitmessage.PinAsync();

Pin for a specified period of time

awaitmessage.PinAsync(newDateTime().AddDays(7));// Pin for 7 days

Unpin a message

awaitmessage.UnpinAsync();

Update message

awaitmessage.UpdateAsync(newStreamUpdateMessageRequest{Text="New changed message",});

Attach custom data to a message

awaitmessage.UpdateAsync(newStreamUpdateMessageRequest{CustomData=newStreamCustomDataRequest{{"CategoryId",12},{"Awards",newstring[]{"Funny","Inspirational"}}}});

Delete a message

Soft Delete

Only clears the text but leaves other related data, reactions, thread sub-messages, etc. intact

awaitmessage.SoftDeleteAsync();

Hard Delete

Removes a message completely and removes all data related to this message

awaitmessageInChannel.HardDeleteAsync();

Add reactions to messages

Simple reaction

awaitmessage.SendReactionAsync("like");

Reaction with custom score

awaitmessage.SendReactionAsync("clap",10);

Add reaction and remove any previous reactions from this user for this message

awaitmessage.SendReactionAsync("love",enforceUnique:true);

Delete reaction:

awaitmessage.DeleteReactionAsync("like");

Upload a file

// Get file byte array however you want e.g. Addressables.LoadAsset, Resources.Load, etc.varsampleFile=File.ReadAllBytes("path/to/file");varfileUploadResponse=awaitchannel.UploadFileAsync(sampleFile,"my-file-name");varfileWebUrl=fileUploadResponse.FileUrl;

Upload an image

varsampleImage=File.ReadAllBytes("path/to/file");varimageUploadResponse=awaitchannel.UploadImageAsync(sampleFile,"my-image-name");varimageWebUrl=imageUploadResponse.FileUrl;

Delete file or image

varchannel=awaitClient.GetOrCreateChannelWithIdAsync(ChannelType.Messaging,channelId:"my-channel-id");awaitchannel.DeleteFileOrImageAsync("file-url");

React to Channel changes

Channel objects are being automatically updated whenever any change occur (new messages, reactions, etc.). You can react to these changes by subscribing to IStreamChannel exposed events:

channel.MessageReceived+=OnMessageReceived;channel.MessageUpdated+=OnMessageUpdated;channel.MessageDeleted+=OnMessageDeleted;channel.ReactionAdded+=OnReactionAdded;channel.ReactionUpdated+=OnReactionUpdated;channel.ReactionRemoved+=OnReactionRemoved;

Get local user or local user data

varlocalUserData=Client.LocalUserData;varlocalUser=localUserData.User;

• Local User Data - Additional data related to the user connected on the local device like: muted channels, list of devices, unread channels, unread messages, etc.
• Local User - instance of StreamUser representing the user on the local device

Get all users

varusers=awaitClient.QueryUsersAsync();

Find user by ID

varusers=awaitClient.QueryUsersAsync(newDictionary<string,object>(){{"id",newDictionary<string,object>{{"$eq",otherUserId}}}});varotherUser=users.First();

Find multiple users by ID

varfilters=newDictionary<string,object>{{"id",newDictionary<string,object>{{"$in",listOfUserIds}}}};varusers=awaitClient.QueryUsersAsync(filters);

Read more on supported query parameters and operators

Add Channel Members

Depending on your app configuration users may need to join channels as members in order to send messages or see other users messages

// Multiple overloads available depending on your needsawaitchannel.AddMembersAsync(user);// instance of IStreamUserawaitchannel.AddMembersAsync(user1,user1);// Multiple instances of IStreamUserawaitchannel.AddMembersAsync(listOfUsers);// List<IStreamUser>awaitchannel.AddMembersAsync("user-id");// string IDawaitchannel.AddMembersAsync(listOfUserIds);// List<string> that contains IDs

Remove Channel Members

// Multiple overloads available depending on your needsawaitchannel.RemoveMembersAsync(member);// instance of IStreamChannelMemberawaitchannel.RemoveMembersAsync(member1,member2);// Multiple instances of IStreamChannelMemberawaitchannel.RemoveMembersAsync(listOfMembers);// List<IStreamChannelMember>awaitchannel.RemoveMembersAsync(user);// instance of IStreamUserawaitchannel.RemoveMembersAsync(user1,user1);// Multiple instances of IStreamUserawaitchannel.RemoveMembersAsync(listOfUsers);// List<IStreamUser>awaitchannel.RemoveMembersAsync("user-id");// string IDawaitchannel.RemoveMembersAsync(listOfUserIds);// List<string> that contains IDs

Moderation

Stream provides all the necessary tools and features to properly manage a large community.

Flagging

Flagging means that this user or message will be reported to the chat moderation. Chat admins and moderators can view reported users and messages in the Dashboard.

Flag a user

awaituser.FlagAsync();

Flag a message

awaitmessage.FlagAsync();

Ban a user

Ban indefinitely

awaitchannel.BanUserAsync(user);

Ban for a specified period of time

awaitchannel.BanUserAsync(user,"You got banned for 2 hours for toxic behaviour.",120);

Ban user IP

Banning IP helps to prevent case where user creates a new account to bypass the ban.

awaitchannel.BanUserAsync(user,timeoutMinutes:120,isIpBan:true);

Ban for a specified period of time

awaitchannel.BanUserAsync(user,"You got banned for 2 hours for toxic behaviour.",120);

Query Banned Users

varrequest=newStreamQueryBannedUsersRequest{CreatedAtAfterOrEqual=newDateTimeOffset().AddHours(-24),Limit=30,Offset=0,};varbannedUsersInfo=awaitClient.QueryBannedUsersAsync(request);

Shadow Banning

Shadow banned user doesn't know he's being banned. This is sometimes helpful because it takes additional time for a user to realize the he's banned.

Shadow ban StreamUser

awaitchannel.ShadowBanUserAsync(user);

Shadow ban StreamChannelMember

awaitchannel.ShadowBanMemberAsync(channelMember);

Mute a user

awaituser.MuteAsync();

Unmute a user

awaituser.UnmuteAsync();

Mute a channel

awaitchannel.MuteChannelAsync();

Unmute a channel

awaitchannel.UnmuteChannelAsync();

Check our documentation for more examples

The above examples are only a few out of many - check out our Full Documentation for more insight and examples

---

Missing any features?

Go ahead and open GitHub Issue with your request and we'll respond as soon as possible.

---

Any issues, bugs, or questions?

Reach out to our Support.

---

We are hiring

We've recently closed a $38 million Series B funding round and we keep actively growing. Our APIs are used by more than a billion end-users, and you'll have a chance to make a huge impact on the product within a team of the strongest engineers all over the world. Check out our current openings and apply via Stream's website.