NAV

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:

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:

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:

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.

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”.

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>/clients
    with 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.

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:

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!

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:

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>/memberships
    with 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>/messages
    with 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!

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:

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>/memberships
with example payload {"is_participating": true, "composing_status": "idle"}

Once againg, 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:

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>/messages
    with 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.