Learn Azure Communication Services Day 15 – Doing Chat in ACS

I’ve been posting daily for the last 15 days and so this will be the last daily post for a little while. I am definitely going to be adding to this series because there are so many areas of Azure Communication Services that I haven’t had a chance to write about yet, but… just not daily!

Today, we’re going to look at something different. We’ve spent a lot of time looking at the VoIP calling platform in ACS, but today I want to explore the chat platform a bit. Inside Azure Communication Services is a full platform for hosting text-based chat, either alongside calling or completely separatly. It also supports Teams Interop to meeting chat, but that’s a subject for another blog post.

The way chat works in ACS is slightly different from how calling works. With calling you could either call someone directly, or use an ID to start or join a group call. With chat, you first need to create a chat thread before you can join it. Further, only people you explicitly name as participants can join the chat, although once they’ve been added they can themselves add more people. This makes our sample code a little more involved because we need to cover creating a new chat thread, joining a thread and adding new people, if we want to have a demo that shows chat working.

Chat services are delivered via a different package so it’s necessary to install that before we do anything else. I’m going to assume you’ve copied one of the earlier samples – anything from Day 5 onwards will be fine.

The chat service code needs to know the URL of your Azure Communication Services endpoint. You can find this by going to the resource in Azure and copying the Endpoint value from the Overview page.

In addition to the other instructions for getting Day 5 up and running, add in this one to install the communication-chat module:

npm install @azure/communication-chat

Here’s the code: don’t forget, on Line 16 replace the placeholder text with your endpoint URL, and on Line 19, replace the placeholder text with the full URL of your Azure Function created in Day 3, including the code parameter:

index.html

client.js

Testing it out

We need two browsers running to test this out, so once you’ve used a command-line to run this command, browse to the sample application in your browser (usually http://localhost:8080), and then open a second private browsing session to the same address:

npx webpack-dev-server --entry ./client.js --output bundle.js --debug --devtool inline-source-map

There’s a few things going on here, so here’s a walkthrough you can follow to try everything out, and then you can play around with it after that.

1. Browser 1 – before we can do anything we need to create a new chat thread to chat in, so click the “Create a Chat Thread” button. You should get an alert with the new ID, which is also placed into the Thread ID box.
2. Browser 1 – the new chat thread is created, but we haven’t connected to it yet. Click “Connect” to do this.  Now we’re connected, but a chat of 1 is a lonely place.
3. Browser 2 – we need to connect to the chat instance that was created in Browser 1, but before we’re allowed to do that we have to be added as a participant. So, copy the User ID from Browser 2 to your clipboard
4. Browser 1 – Once you’ve connected to the chat thread, paste the User ID into the User ID box at the bottom and click “Add User”. This adds the user from Browser 2 to the chat thread.
5. Browser 2 – Copy the Chat Thread ID from out of the input box in Browser 1 and paste it into the “Chat Thread ID” box. Click Connect to join the chat thread created by Browser 1.
6. Browsers 1 & 2 – now, both browsers should now be able to send messages using the “Type your message” and “Send” elements, and see the conversation show up in the browser.
7. Party!

What’s the code doing?

• The chat client is created in the init() function on line 32. Unlike the calling client, it needs the ACS Endpoint.
• If you want to receive notifications about new messages in a chat thread you have to opt-in to them with the startRealtimeNotifications method. You have to do this before you subscribe to the chatMessageReceived event (even though that feels wrong to me!) (lines 44-52)
• A chat client can tell you about notifications to more than one chat thread. Setting up chat threads, adding participants and sending messages all happens on a ChatThreadClient (not the ChatClient).
• We set up a chat thread with no additional participants (line 79) but you could do so if you knew their IDs ahead of time. It’s not necessary to add yourself.
• There are a whole bunch of interesting methods we didn’t explore because this sample was already large enough. You can list all messages in a chat, delete messages, send and receive read receipts, send typing notifications and more. If you’re interested, have a look at the ChatThreadClient Class Definition.

Today, we explored using the chat platform to send and receive chat messages in two different browsers. Links for all blog posts can be found at learnACS.dev. You can also subscribe to my YouTube channel for videos about ACS (and much more!).

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.

---

Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Related posts:

Learn Azure Communication Services Day 12 – Showing Screen Share Content Learn Azure Communication Services Day 11 – Changing Audio & Video Devices Learn Azure Communication Services Day 1 – What is Azure Communication Services (ACS), an Introduction Learn Azure Communication Services Day 3 – Let’s Code! Creating a back-end Token Issuing Function in Azure Functions Learn Azure Communication Services Day 9 – Muting and Unmuting