Unity Chat Tutorial:
In-Game Messaging

Set up your development environment

In this tutorial, we will use the Stream Chat API and the Unity SDK Plugin to add in-game chat to a new Unity Engine project.

Before you start: Make sure you have Unity Editor installed on your system. If not you can download it here.

We'll be using the latest at the time of writing version - 2022.1.23f1 but any version starting from 2020.1 up to the most recent ones should work fine as well.

Create a new Unity project

Open Unity Hub and create a new project using the 3D template.

Create a new unity project preview

We'll name our project Stream Chat Introduction Tutorial.

Download the Unity Chat Assets

The Unity Chat SDK includes a fully stateful client that enables you to easily interact with the Stream Chat API and automatically handles state updates.

First, you want to make sure you've downloaded the latest release of the Stream Chat Unity Package from the Releases page of the GitHub repository and imported it into the project.

Import Stream SDK preview

Newtonsoft Json Conflict Resolution

Stream Chat SDK uses a Unity's Newtonsoft Json package for the internal web requests serialization. Since Json is a one of the most commonly used libraries, it is quite likely that you already have this library in your project, or you might be using a Unity Editor version that has Newtonsoft Json package pre-installed.

In such case you might notice that Unity has already excluded this folder from import as shown below. Unity skips import of Json folder

Alternatively, you may find a "Multiple precompiled assemblies with same name Newtonsoft.Json.dll..." error showing in the Unity Editor's console as shown below. Unity console Json conflict

In this case you can simply delete the com.unity.nuget.newtonsoft-json@3.0.2 folder located in the StreamChat/Libs/Serialization path or delete the other Json library already present in your project and use Unity's Json package contained within the Stream SDK.

Once you have the Chat SDK imported and there are no errors in Unity's Console, we can move forward.

Create new Scene

Open the Scenes folder, create a new scene and rename it to Stream Chat Tutorial

Open new scene preview

Now open the newly created Stream Chat Tutorial scene.

Add new Game Object

Go to the Hierarchy window, create a new Game Object and rename it to ChatManager. This Game Object will initialize the Stream Chat SDK Client.

Create new game object

Add new Script

Go to the Project window, create a new C# script and rename it to ChatManager.cs and open it in an editor of your choice (in this tutorial we'll be using JetBrain's Rider) and paste in the following code:

In the above script, we've defined a private variable private IStreamChatClient _chatClient; to hold a reference to our chat client instance. Next in the Unity's special Start method we've called the _chatClient = StreamChatClient.CreateDefaultClient(); factory method that creates and configures the chat client instance.

You should always have only single instance of the Stream Chat Client

Now add the StreamChatBehaviour.cs to the StreamChatClient Game Object as a component:

Attached script to game object

Connect a User

First, let's define an async method that will connect our user to the Stream Chat server and print a log once the connection is established.

Now, in the Start method, add this line after creating the chat client:

Because we're calling an asynchronous method from a synchronous Start method, we might not catch an exception if thrown by the StartChatAsync method. We can cover this by chaining the Stream's LogExceptionsOnFailed extension method at the end.

[Click to expand] Full example of ChatManager.cs file after completing the above steps.

In a production scenario, user tokens should be generated using a backend and our server SDK.

Test Connection!

Go ahead and play the scene. You should now see logs confirming that we have established a valid connection with the Stream Server.

Valid connection with the Stream Server

Create a new channel

Now that our connection is established we can create a new channel to which our logged user will send messages.

We'll create a channel of type "messaging" which has preconfigured permissions for a messaging application. Channel types are configurable and you can create your own types as well in our Dashboard. You can read more on our permissions system and predefined channel types here.

First, let's add a private variable to hold the reference to our channel:

Next, add this line to the end of StartChatAsync method:

[Click to expand] Full example of ChatManager.cs file after completing the above steps.

Once you save the script and play the scene you should now see a log confirming that we now have a channel with "main" ID.

Confirmed new channel creation

This ensures that the requested channel is created on the server and we can start sending messages.

Observe changes in the channel

Before we send any message we should subscribe to IStreamChannel events in order to be notified on any updates. Let's create 3 methods that will be triggered by the Chat Client instance when:

  1. a new message is received
  2. a message is deleted
  3. a reaction is added to a message

Now we can subscribe above methods in the StartChatAsync method:

Also, it's a good practice to unsubscribe from the subscribed events. This will avoid cases where our object cannot be garbage collected due to being subscribed to a different object if their lifetimes differ. We can do it in the Unity's special OnDestroy method:

[Click to expand] Full example of ChatManager.cs file after completing the above steps.

Send new message

Finally, we can start sending messages! To simplify things, we'll skip the UI integration and send a new message every time you press the letter S on your keyboard.

First, add this method to the ChatManager class:

To keep things organized, we'll add it right after the StartChatAsync method.

Next we'll use the Unity's special Update method, that gets automatically called by the Unity Engine every frame. Add this piece of code right after the Start method:

Let's go through what's going on here. We only want to send message if we're both connected and have the main channel created. Therefore at the beginning of the Update method, if we're not connected !_chatClient.IsConnected or our main channel is not created _mainChannel == null we early exit the method.

Once both of these conditions are met we check if the player pressed the S key with Input.GetKeyDown(KeyCode.S) and everytime he does, we'll execute our SendMessageAsync method that we've added previously to our class. Please note that we're chaining the async method with LogExceptionsOnFailed() extension. This will log errors in case our message sending fails.

Finally, in our SendMessageAsync method, we execute await _mainChannel.SendNewMessageAsync(text); to send the message.

[Click to expand] Full example of ChatManager.cs file after completing the above steps.

Test sending messages

Now, hit the play button and press the S key few times on your keyboard. You should now see new logs that confirm both that our message was sent and received by the channel.

New message confirmation

What good is sending messages if you can't read them, right? Let's iterate and print all of the channel messages when the channel is loaded. Paste this code at the end of StartChatAsync method:

[Click to expand] Full example of StartChatAsync method after completing the above steps.

If you press the play button now, you should see messages that you've sent in the previous steps.

New message confirmation

Delete messages

Lastly, let's see how easy it is to delete a message. We'll add a simple feature that tries to delete the last message on a key press.

Add this piece of code to the end of the Update method:

When a user presses the D key, we check whether there are any messages in the channel. If channel has not messages we print the No message to delete log, otherwise we take the last message with _mainChannel.Messages.Last() and hard delete it with lastMessage.HardDeleteAsync(). Again, because we're not awaiting the HardDeleteAsync() we add the LogExceptionsOnFailed() extension method to the end in order to print any errors if the delete request fails.

[Click to expand] Full example of ChatManager.cs file after completing the above steps.


We hope that you've enjoyed this tutorial on gaming chat with Unity. By using Stream’s chat components, you and your team will be able to get your Unity Game or Application up and running with in-game chat in minutes.

Now that you’ve completed the tutorial on Unity Chat, you can build anything chat related with our components. If you have a use-case that doesn’t quite seem to work, or simply have questions, please don’t hesitate to reach out here.

Final Thoughts

In this chat tutorial we've covered the most basic interaction with the low-level SDK.

The API has plenty more features available to support more advanced use-cases such as push notifications, content moderation, rich messages and more, and the chat SDK for Unity is undergoing heavy development to include all functionality.

Give us Feedback!

Did you find this tutorial helpful in getting you up and running with Unity for adding chat to your project? Either good or bad, we're looking for your honest feedback so we can improve.

Kiddom logo

We’ve been going at lightspeed to build more communication functionality into Kiddom. The only way to achieve this in four months was to do a chat integration with Stream because we needed to do it reliably and at scale.

Head of Product, Kiddom profile picture

Nick Chen

Head of Product, Kiddom

Next Steps

Create your free Stream account to try out all our Chat product has to offer. No commitment or credit card required. If you want a custom plan or have questions, we are eager to talk with you.

Activity Feeds

Build any kind of feed without the headache of scalability or reliability of your feeds.

Learn more about $ Activity Feeds


Available 99.999% uptime SLAs and industry-leading security to power the world's largest apps.

Learn more about $ Enterprise