Unity Chat Tutorial:
In-Game Messaging


Set up your development environment
Confused about "Set up your development environment"?
Let us know how we can improve our documentation:
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
Confused about "Create a new Unity project"?
Let us know how we can improve our documentation:
Open Unity Hub and create a new project using the 3D template.
We'll name our project Stream Chat Introduction Tutorial
.
Download the Unity Chat Assets
Confused about "Download the Unity Chat Assets"?
Let us know how we can improve our documentation:
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.
Newtonsoft Json Conflict Resolution
Confused about "Newtonsoft Json Conflict Resolution"?
Let us know how we can improve our documentation:
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.
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.
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
Confused about "Create new Scene"?
Let us know how we can improve our documentation:
Open the Scenes folder, create a new scene and rename it to Stream Chat Tutorial
Now open the newly created Stream Chat Tutorial scene.
Add new Game Object
Confused about "Add new Game Object"?
Let us know how we can improve our documentation:
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.
Add new Script
Confused about "Add new Script"?
Let us know how we can improve our documentation:
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:
Connect a User
Confused about "Connect a User"?
Let us know how we can improve our documentation:
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.
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!
Confused about "Test Connection!"?
Let us know how we can improve our documentation:
Go ahead and play the scene. You should now see logs confirming that we have established a valid connection with the Stream Server.
Create a new channel
Confused about "Create a new channel"?
Let us know how we can improve our documentation:
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.
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.
This ensures that the requested channel is created on the server and we can start sending messages.
Observe changes in the channel
Confused about "Observe changes in the channel"?
Let us know how we can improve our documentation:
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:
- a new message is received
- a message is deleted
- 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.
ChatManager.cs
file after completing the above steps.Send new message
Confused about "Send new message"?
Let us know how we can improve our documentation:
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.
ChatManager.cs
file after completing the above steps.Test sending messages
Confused about "Test sending messages"?
Let us know how we can improve our documentation:
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.
Print channel messages
Confused about "Print channel messages"?
Let us know how we can improve our documentation:
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.
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.
Delete messages
Confused about "Delete messages"?
Let us know how we can improve our documentation:
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.
ChatManager.cs
file after completing the above steps.Congratulations!
Confused about "Congratulations!"?
Let us know how we can improve our documentation:
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.
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.
Nick Chen
Head of Product, Kiddom