Skip to content

Chat bots

Developing chatbots

Introduction

Here we will guide you through the integration process of your chatbot app and giosg step-by-step. Before reading this, you should first learn the basics about creating giosg apps from the giosg apps development documentation. We will mostly focus on different use cases and what webhooks you should define for your application.

The following giosg app features are essential for the chatbots:

  • Bot users. For your app, there will be a bot user for each organization who has installed the app.
  • Webhooks. Your bot needs to be notified when e.g. a new chat message is being sent, and it also needs a way to authorize its actions. These are achieved using HTTP webhooks.
  • giosg HTTP API. Bots perform actions (e.g. send chat messages) by making HTTP requests to these endpoints, using the access token received via webhooks.

After reading this guide, you can also take a look at the example demo chatbot.

Creating a bot app

You need to create a bot app like any other giosg app, as described in the giosg apps documentation. Remember that you need to enable the following settings:

  • Ensure that "Automatically create a bot user on installation" checkbox is enabled.
  • Ensure that you have configured the webhooks as described later in this chapter.

About chat routing

Please note that webhooks are only delivered after the bot app has been installed to an organization. Also, note that most of the chat-related webhooks are only delivered if the bot user has been added to a router and that router is being used in at least one room.

The routing is done by the account who installs the app, not the one providing the bot. You can of course install the app to your own organization.

Main use cases

All chatbot use cases follow mostly the same patterns, except for few differences. Roughly speaking, chatbots are divided in two types:

  • Chatbots that chat in behalf of a real human users
  • Chatbots that chat or perform other actions in parallel with real human users

The difference in these cases is whether or not the chatbot handles the chat "all by themselves", reserving the active chats to themselves, unless it decides to transfer it to another user or otherwise stop chatting in it. For example, a chatbot with a capable AI could try to help a customer in a chat, until the issue is resolved or it decides to invite a another user to the chat.

This kind of chatbots have one major requirement: they need to be present in the giosg system. Only users that are present can reserve chats to themselves. If they are not present, they can participate the chat, but pending chats are made available to other users and they will join them as well. This is discussed in more detail in the next sections.

Alternatively, the chatbot may just work in the background, probably helping other users in chats by reacting to specific chat messages. For example, it could send product information to the chat whenever a specific product is mentioned, or could suggest what the user could answer to the visitor instead of sending chat messages by itself. The visitor is primarily still chatting with a live person, and the bot acts as a side-kick.

If the bot actively participates in chats, there are typically two kind of approaches how they start chatting. Depending on this approach, the chatbot webhooks are configured slightly differently, as they should get notified in slightly different situations.

  • Chatbot reactively starts chatting with the visitor, after the visitor has started a new chat. The chatbot should get notified whenever there is a new pending chat available for them.
  • Chatbot proactively starts chatting with the visitor, before the visitor has sent any message. The chatbot should get notified whenever there is a new routed chat available for them.

Authentication to the API

When the chatbot performs actions or reads data using giosg HTTP API, they need to authenticate themselves with HTTP headers. With chatbots this is made easy: they just use the authorization information provided to them via webhooks, as described in "Reacting to webhooks".

Success

Your bot does not have to store any API tokens to a long-term storage! It can (and should) always use the fresh token they receive from the webhook HTTP requests!

In the following sections, whenever we advice using an HTTP API endpoint, you should follow the steps described in the giosg apps documentation! Basically, they just read the access_token and token_type attributes from the app_user_auth object, and use it in the HTTP header: Authorization: <token_type> <access_token>

Making the chatbot present

It is strongly recommended that the bot user keeps themselves "present" in the giosg system. This is required if your bot wants to "take" chats to themselves so that they are not made available to other users as "pending" chats.

In the giosg system, users are made "present" by creating and updating user clients for the particular user. If they do not have one yet, a new one is created. Otherwise, an existing one can be updated. Each user client is marked to be present for a limited amount of time. Therefore, user clients need to be refreshed by updating them, in order to keep the user present. A user is considered present if they have at least one present user client.

For chatbots, the recommended approach is that whenever the bot receives any webhook to which it intends to react, then as the first thing it refreshes its presence. The procedure goes like this:

  1. List the previously created "user clients" for the bot user: GET /api/v5/users/<user_id>/clients

  2. If no user client was found, then register a new one, by creating it with some expiration time: POST /api/v5/users/<user_id>/clientswith example payload {"presence_expires_in": 28800}

  3. Otherwise, refresh any one of the listed user clients by updating their expiration time: PATCH /api/v5/users/<user_id>/clients/<client_id>with example payload {"presence_expires_in": 28800}

Each of the HTTP API requested mentioned above must be authorized as described in the giosg apps documentation.

Online status of the chatbot

Just like normal users, chatbots can be "online".

This will affect the behaviour of the "chat button" on customer web pages. The button is shown when there exists at least one user that is online and the chat can be routed to them. If the chatbot is set to be online, it can receive new chats even when all human users are offline.

Additionally, with default settings, autosuggest messages will use the name of randomly chosen user who is online. Setting the chatbot online means that it can show as the sender of an autosuggest message. With rules, the autosuggest message sender can be set to be one specific user for all messages. Chatbot doesn't need to be online if it is used as the autosuggest message sender for all autosuggest messages.

You can set the chatbot online or offline by updating the is_online_enabled field of the chatbot by using: PATCH /api/v5/users/<user_id>with example payload {is_online_enabled: true}.

The is_online field holds the actual online state of the user. The state is true when is_online_enabled is set to true and is_present is true. Otherwise, it is false.

Handling routed chat messages

The simplest approach to implement a chatbot is to just get notified about every chat message in any of the chats available for the bot user, and reacting to these accordingly. For example, this is useful for bots that are triggered by certain keywords in any chat message.

To get notified by all new messages in any of the chats "routed" to the chatbot, the following webhook is the only one your bot needs:

  • Channel pattern: /api/v5/users/{user_id}/routed_chats/*/messages
  • Enable checkbox "Subscribe to additions"

The received objects are chat message resources. Note that you will receive a lot of different kinds of messages, not just actual chat messages! The bot will also get notified about chat messages they have sent themselves!

Typically, if the chatbot is only interested in actual messages sent by visitors, then it should only handle messages whose type is msg and sender_type is visitor, and ignore everything else. Please check the reference for the chat message attributes for more options!

Warning

It is important to understand that with this approach, the bot may also be notified about all messages in any conversation, even between between a visitor and another user. It is the bot's responsibility to decide when and how it should react to the messages, and not to disturb other users.

The bot has numerous options how to react to these webhooks! The first thing to do should be refreshing their presence, as described above. After this, it can for example:

Start chatting reactively

Typically, chatbots may act like human chat agents in the way that they wait until they get notified about a new pending chat available for them. This means that a visitor has either started a new chat, or they sent a response to a proactive autosuggest message. In either case, the visitor waits to be served.

To configure the bot to receive notifications about new pending chats, add a webhook with the following details:

  • Channel pattern: /api/v5/users/{user_id}/pending_chats
  • Enable checkbox "Subscribe to additions"

Now the chatbot server will be requested to the provided URL for each new pending chat. If the chatbot wants to "take" this chat to themselves and start chatting in this chat, it requires to do the following things:

  1. The chatbot user ensures that they are present in the giosg system, as described earlier

  2. The chatbot user "joins" the chat, i.e. becomes a member of the chat, by creating a chat membership to the pending chat: POST /api/v5/users/<user_id>/pending_chats/<chat_id>/membershipswith example payload {"is_participating": true, "composing_status": "idle"} The is_participating value should be true if the bot wants to "reserve" the chat to itself, removing it from the "pending chats" of all users. The composing_status tells whether or not the user is currently "typing", as shown in the chat window. As bots are not using a physical keyboard, this should always be "idle".

  3. If the bot gets a 404 error response when attempting to create the membership, this means that some other user has already joined this chat, and the chat is no longer pending. The bot should then just ignore the chat.

  4. Once joined successfully, the chatbot reads any previous chat history by listing chat messages of the chat GET /api/v5/users/<user_id>/chats/<chat_id>/messages

  5. The bot may send as many chat messages as it wants. Optionally, it can add rich content by using chat message attachments. POST /api/v5/users/<user_id>/chats/<chat_id>/messageswith example payload {"message": "Nice to meet you!"}

Each of the HTTP API requested mentioned above must be authorized as described in the giosg apps documentation.

This procedure is for joining new chats. After this, the chatbot needs to get notified about every new chat message in chats where the bot is a member, as described below!

Warning

Because of the real-time nature of the chat, you need to consider race conditions in your bots' functionality.

In the giosg system, when a visitor starts a new chat, the following things happen:

  1. A new chat is created to the system. At this point, depending on your configuration, your bot might already receive a webhook channel.
  2. A new chat message is created to the chat. Other webhooks may be sent at this point.

Let's say that your bot receives information about the chat right after step 1, but before step 2, and they start loading the list of chat messages in the chat. In this case, it is totally possible that the bot gets a webhook notification about the same chat message that is also returned in the message list.

Luckily, each resource in the giosg system, including chats and chat messages, have unique IDs that you can use to keep track of which resources your bot has already handled! You just need to pay attention to this possibility when implementing your bot.

Start chatting proactively

Alternatively, chatbots may want to join the chat immediately after a new chat is initialized in the giosg system, but before the visitor has sent a message. This use case works very similar to the one described in the previous chapter, except that the configured webhook should be bound to routed chats of the user:

  • Channel pattern: /api/v5/users/{user_id}/routed_chats
  • Enable checkbox "Subscribe to additions"

Now the chatbot server will be requested to the provided URL for every new chat routed to them, not just pending chats. If the chatbot wants to "take" this chat to themselves and start chatting in this chat, it performs the same steps as described in the previous section, except that it should join a routed chat, not to a pending chat:

POST /api/v5/users/<user_id>/routed_chats/<chat_id>/membershipswith example payload {"is_participating": true, "composing_status": "idle"}

Once again, the is_participating value should be true if the bot wants to "reserve" the chat to itself, possibly removing it from the "pending chats" of all users. The composing_status tells whether or not the user is currently "typing", as shown in the chat window. As bots are not using a physical keyboard, this should always be "idle".

With this approach, you should also be aware of the race condition possibilities, as described in the previous section.

In addition to this webhook, the bot is likely to want to receive notifications about new chat messages. If the bot is interested in…

Continue chatting

After joining the chat, the chatbot needs to get notified about every new chat message in chats where the bot is a member. To configure the bot to receive notifications about every new message in their chats, add a webhook with the following details:

  • Channel pattern: /api/v5/users/{user_id}/chats/*/messages
  • Enable checkbox "Subscribe to additions"

Now the chatbot server will be requested to the provided URL for each new chat message. The bot should handle them with the following steps:

  1. Check if the message is actually interesting to the bot. Please note that the bot will receive notifications about all messages in the chat, including ones they have sent themselves! Typically, if the chatbot is only interested in actual messages sent by visitors, then it should only handle messages whose type is msg and sender_type is visitor, and ignore everything else.

  2. If the chatbot decides to handle the message, it should ensure that it is present in the giosg system, as described earlier

  3. The bot may send as many chat messages as it wants. Optionally, it can add rich content by using chat message attachments. POST /api/v5/users/<user_id>/chats/<chat_id>/messageswith example payload {"message": "Nice to meet you!"}

Each of the HTTP API requested mentioned above must be authorized as described in the giosg apps documentation.

Further reading

There is an example demo chatbot, whose source code is publicly available! You can use it to get a better understanding how to implement chatbots, or you can even fork the repository and use it as a starting point for your chatbot implementation.

Also, you could browse through the HTTP API reference and use it as a catalogue for the actions the bot can perform.