Skip to content

Control AI Chatbot via APIs

This document provides instructions for controlling a chatbot via APIs. It includes descriptions and examples of the relevant APIs to manage conversation states, trigger responses, and handle variables.

Conversation state

The conversation state contains information and settings about the bot's and visitor's current conversation.

Attribute Type Default value Description
id UUID read-only The unique identifier of this state.
org_id UUID read-only The unique identifier of the organization that owns this state.
created_at datetime read-only The date and time this state was created.
updated_at datetime read-only The date and time this state was last updated.
visitor_id UUID read-only The unique identifier of the visitor to whom this state belongs. This is the same as the sender_id in chat messsages.
bot_id UUID read-only The unique identifier of the bot to whom this state belongs. Note that this is not the id of the giosg user, but instead id of the bot used in the AI Chatbot API.
force_bot_to_answer_next_message boolean false If true, the bot will answer the next message sent by the visitor even if human agents are participating in the conversation, causing the bot to usually stay quiet. This value is turned false automatically after the next message is sent by the bot. Note that once bot has answered, it will keep answering until it transfers the conversation to a human agent.
answer_to_message_from_any_room boolean false If true, the bot will answer to messages sent from any room. If false, the bot will only answer to messages sent from rooms listed in the bot's settings.
is_deleted_on_chat_end boolean true If true, the state will be deleted when the chat ends. If false, the state will be kept after the conversation ends. On delete the state's variable values are also deleted. On next visitor's message the state is recreated with default values.
is_deleted_on_chat_transfer boolean true If true, the state will be deleted when the chat is transferred to a human agent. If false, the state will be kept after the conversation is transferred. On delete the state's variable values are also deleted. On next visitor's message the state is recreated with default values.
conversation_step UUID None Conversation steps contain information on which knowledge bases are used by the bot when talking with the visitor. These steps are currently not available via API for listing or editing. Only way to change conversation step is setting the switch knowledge bases action after bot's answer.

Conversation state APIs

Conversation state can be fetched with the following API call:

GET https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/state

Conversation state can be edited with the following API call:

PATCH https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/state

And deleted with the following API call:

DELETE https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/state

The bot_id can be aquired from the API that lists all bots in the organization:

GET https://service.giosg.com/api/chatbot/setup/orgs/{org_id}/bot_users

Visitor id can be aquired from the visitor's chat messages. The sender_id in the chat messages is the visitor id.

Conversation state variables

Conversation state variables are key and value pairs linked to a conversation state. Users can add variables to knowledge base reply messages. The variables are then replaced with their values when the message is sent to the visitor. The variables can be used to store situation specific information. For example, if there exists a knowledge base with answers about a product, the product's specific information such as the name or the price can be stored in variables and the same knowledge base can be used to answer questions about different products.

Attribute Type Default value Description
id UUID read-only The unique identifier of this variable.
org_id UUID read-only The unique identifier of the organization that owns this variable.
created_at datetime read-only The date and time this variable was created.
updated_at datetime read-only The date and time this variable was last updated.
key string required The key of this variable. The key is used to identify the variable in knowledge base reply messages. The key must start with a letter or underscore and only contain letters, numbers and underscores. The key must also be unique within the conversation state.
value string required The value of this variable. The value is used to replace the variable in knowledge base reply messages.
type string text The type of this variable. Currently only text is supported.
conversation_state UUID read-only The unique identifier of the conversation state to whom this variable belongs.

Conversation state variable APIs

Conversation state variables can be listed with the following API call:

GET https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/variables

Conversation state variables can be created with the following API call:

POST https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/variables

Single conversation state variable can be fetched with the following API call:

GET https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/variables/{variable_id}

Single conversation state variable can be edited with the following API call:

PATCH https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/variables/{variable_id}

And deleted with the following API call:

DELETE https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/variables/{variable_id}

Note that in addition to defining variable values to the scope of the conversation state, one can also define variable values using the visitor variables API of giosg live. The visitor variables are not tied to the conversation state and are not deleted when the conversation ends or is transferred to a human agent.

Trigger bot messages using API

Bot can be triggered to send a message to the visitor using two different APIs. The first one makes the bot react to a visitor message defined in the API, and the second one makes the bot send a message defined in the API.

Trigger bot to react to a visitor message

Bot can be triggered to react to a visitor message using the following API call:

POST https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/trigger_reaction

The body of the request must be formatted similarly as the following JSON:

1
2
3
4
5
{
  "visitor_message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "visitor_message": "Do you sell fish?",
  "chat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Here, either visitor_message_id or visitor_message must be defined. If visitor_message_id is defined, the bot will react to the visitor message with the given id. If visitor_message is defined, the bot will react to the visitor message with the given text. It is recommended to use visitor_message_id if the visitor message id is known, as it allows the bot to also send reply suggestions.

The chat_id is optional. If it is defined, the bot will send the message to the chat with the given id. If it is not defined, the chat is the one where the bot has most recently answered to the visitor. The chat_id is only required if the bot has never answered to the visitor before in their current chat.

Trigger bot to send a message

Bot can be triggered to send a message using the following API call:

POST https://service.giosg.com/api/chatbot/conversation/orgs/{org_id}/bot_users/{bot_id}/visitors/{visitor_id}/trigger_answer

The body of the request must be formatted similarly as the following JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "answer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "answer": {
    "answer_messages": [
      {
        "type": "answer text",
        "text": "Yes, We sell fish.",
        "place_of_usage": "main answer"
      },
      {
        "type": "answer interaction",
        "interaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "title": "Fish buying interaction",
        "place_of_usage": "main answer",
        "parameters": {
          "parameter1": "value1",
          "parameter2": "value2"
        }
      }
    ],
    "next_conversation_step": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tags": ["sales", "fish"],
    "multiple_answer_delay": 2,
    "after_answer_behavior": "nothing"
  },
  "chat_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Here, either answer_id or answer must be defined. If answer_id is defined, the bot will send the answer with the given id. If answer is defined, the bot will send the given answer.

The chat_id is optional. If it is defined, the bot will send the message to the chat with the given id. If it is not defined, the chat is the one where the bot has most recently answered to the visitor. The chat_id is only required if the bot has never answered to the visitor before in their current chat.

The answer object must contain the following fields:

Field Type Required Description
answer_messages array required The messages to be sent as the answer. The messages are sent in the order they are defined in the array.
next_conversation_step UUID optional The next conversation step to be used after the answer has been sent. If this is not defined, the conversation step is not changed. Only applies if the after_answer_behavior is set conversation step.
tags array optional The tags to be added to the chat after the answer has been sent.
multiple_answer_delay integer optional The sending delay in seconds between the answer messages.
after_answer_behavior string optional The behavior to be used after the answer has been sent. Possible values are nothing, set conversation step, set as waiting and end chat. If this is not defined, the behavior is nothing.

The answer_messages array must contain either answer text or answer interaction objects. The answer text object must contain the following fields:

Field Type Required Description
type string required The type of the message. Must be answer text.
text string required The text to be sent as the message.
place_of_usage string optional The place of usage of the message. Possible values are main answer, online fallback answer and offline fallback answer. If this is not defined, the place of usage is main answer. The fallback answer messages are used if the after_answer_behavior is set as waiting. If an agent is online, the main answer and online fallback answer messages are sent to the visitor. If all agents are offline, the main answer and offline fallback answer messages are sent to the visitor.

The answer interaction object must contain the following fields:

Field Type Required Description
type string required The type of the message. Must be answer interaction.
interaction_id UUID required The id of the interaction to be sent as the message.
title string optional The title of the interaction to be sent as the message. This is shown to operators in their chat window.
place_of_usage string optional The place of usage of the message. Possible values are main answer, online fallback answer and offline fallback answer.
parameters object optional The parameters to be sent to the interaction. These parameters are available as query parameters to the interaction and can be accessed using custom javascript. The parameters are sent as key-value pairs.

Trigger bot using an action message

If an action message is sent to chat, bot will react to it. More specifically, bot reacts to a message where type field has value action. In this case, the text in response_value field is reacted to by the AI chatbot.

This allows you to trigger bot answer from interactions or external attachments using post messages as documented in rich text messages tutorial.