Creating a usable Bot

note

The enpoints listed below assume that the base url is that of UCI-API service.

Prerequisites

Before you begin, you must have the necessary credentials for the platform you are creating your bot for. Take a look at supported channels and providers to get details about how to generate credentials for your selected channel and provider.

Setting Secret Credentials

Once you are ready with the credentials for your provider, you need to send these credentials to Bharat SahAIyak. Here's how you create secrets.

POST

/admin/secret Create a secret credential

Headers

Name	Type	Required	Description
Authorization	String	YES	JWT token of the logged in user.

Request Body

Name	Type	Required	Description
variableName	String	YES	The name of the secret which identifies the secret. Can be anything of your choice (only alphanumeric characters without spaces).
secretBody	JSON	YES	The credentials that you want to create in a JSON format (key-value pairs).

Curl Request

curl --location 'UCI_API_BASE_URL/admin/secret' \
--header 'Authorization: YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "variableName": "myTestVariable",
    "secretBody": {
        "var1": "val1",
        "var2": "val2",
        "var3": "val3",
        ...
    }
}'

note

Keep the variableName handy since we'll use that in later steps.

Setup Adapter

Once you have your secrets set up you need to create an adapter object for your bot or use an existing adapter that you might have already created. Skip this section if you already have an adapter which you want to use.

POST

/admin/adapter Create an adapter instance.

Headers

Name	Type	Required	Description
Authorization	String	YES	JWT token of the logged in user.

Request Body

Name	Type	Required	Description
name	String	YES	The name of the adapter. Can be anything of your choice (only alphanumeric characters without spaces).
channel	String	YES	The channel that you want to use the bot on, for example, Whatsapp, Pwa, etc. To get a complete list of supported channels take a look at supported channels.
provider	String	YES	The provider that provides you messaging services, for example, gupshup, twilio, etc. To get a complete list of supported providers take a look at supported channels.
config	JSON	YES	Adapter config which contains meta data.
config.credentials	JSON	YES	Credentials for the provider that is being used. See Setting Secret Credentials for details.
config.credentials.variable	String	YES	The secret name for your credentials. See Setting Secret Credentials for details

Attention

The channel and provider values are case-sensitive and 'must' be used as listed in supported channels.

Curl Request

curl --location 'UCI_API_BASE_URL/admin/adapter' \
--header 'Authorization: YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "name": "TestAdapter",
    "channel": "Whatsapp",
    "provider": "Gupshup",
    "config": {
        "credentials": {
            "variable": "YOUR_SECRET_NAME"
        }
    }
}'

note

Keep the generated adapter id handy since we'll use that in later steps.

Setup Transformer

A transformer is what defines the logic of the bot. Skip this section if you already have a transformer which you want to use.

POST

/admin/transformer Create a transformer instance.

Headers

Name	Type	Required	Description
Authorization	String	YES	JWT token of the logged in user.

Request Body

Name	Type	Required	Description
name	String	YES	The name of the transformer. Can be anything of your choice (only alphanumeric characters without spaces).
config	JSON	NO	Config attached to a transformer.

Curl Request

curl --location 'UCI_API_BASE_URL/admin/transformer' \
--header 'Authorization: YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "name": "TestTransformer",
    "config": {}
}'

note

Keep the generated transformer id handy since we'll use that in later steps.

Setup Conversation Logic

A conversation logic binds an adapter with a transformer config. It also defines a logic definition which governs how a message flows throught the system (How different types of models are used and in what sequence). Skip this section if you already have a conversation logic which you want to use.

POST

/admin/conversationLogic Create a conversation logic instance.

Headers

Name	Type	Required	Description
Authorization	String	YES	JWT token of the logged in user.

Request Body

Name	Type	Required	Description
name	String	YES	The name of the conversation logic. Can be anything of your choice (only alphanumeric characters without spaces).
description	String	NO	The description of the conversation logic.
transformer	String	YES	The id of the transformer that you want to attach to this bot. See Setup Transformer for creating a transformer.
adapter	String	YES	The id of the adapter that you want to attach to this bot. See Setup Aadapter for creating a new adapter.
logicDef	JSON	YES	This is the xstate config which governs the flow of a message in the system.

Curl Request

curl --location 'UCI_API_BASE_URL/admin/conversationLogic' \
--header 'Authorization: YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "name": "TestBotLogic",
    "description": "This is a test bot logic",
    "transformer": "ce6afffa-1d5f-4748-8f25-37a1d9caa91b",
    "adapter": "656a23e8-96c0-4b40-8bfa-816bbbfbbfea",
    "logicDef": {}
}'

note

Keep the generated conversation logic id handy since we'll use that in later steps.

Setup User Segment (Optional)

A User Segment is a config which binds a bot to a group of users. After a bot is bound to a user, the access to this bot is restricted to only that group of users which a User Segment defines. Apart from this, a User Segment is required if you want to broadcast a message to a group of users. Skip this section if you want your bot to have public access or already have a User Segment that you want your bot to bind to.

Prerequisite

For binding a bot to a User Segment, an external User Managment Service is required to be up and running. The Bharat SahAIyak repo provides a demo User Management Service, but it should not be used for production systems. You can create your own User Management Service by following the guide here.

Once you have the User Management Service setup, you need to create a User Segment instance.

POST

/admin/user-segment Create a user segment instance.

Headers

Name	Type	Required	Description
Authorization	String	YES	JWT token of the logged in user.

Request Body

Name	Type	Required	Description
name	String	YES	The name of the user segment. Can be anything of your choice.
url	String	YES	The url of the external user management service. See prerequisite section for details.
category	String	YES	The catergory of the user segment. Can be anything of your choice.

Curl Request

curl --location 'UCI_API_BASE_URL/admin/user-segment' \
--header 'Authorization: YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "url": "MY_USER_MANAGEMENT_SERVICE_ENDPOINT",
    "name": "User Segment Test",
    "category": "Whatsapp"
}'

note

Keep the generated user segment id handy since we'll use that in later steps.

Creating a Bot

Now that we have all the things required, its finally time to create a bot instance.

POST

/admin/bot Create a bot instance.

Headers

Name	Type	Required	Description
Authorization	String	YES	JWT token of the logged in user.

Request Body

Name	Type	Required	Description
startingMessage	String	YES	The starting message of the bot with which it can be triggered. can be anything of your choice, but it must be unique within an org.
name	String	YES	The name of the bot. Can be anything of your choice (only alphanumeric characters without spaces).
startDate	String	YES	The start date of the bot in (yyyy-mm-dd) format.
endDate	String	YES	The end date of the bot in (yyyy-mm-dd) format.
logic	String	YES	The id of the conversation logic that you want to attach to this bot. See Setup Conversation Logic for creating a new conversation logic.
users	String	NO	The id of the user segment that you want to attach to this bot. See Setup User Segment for creating a new user segment.
description	String	NO	The description of the bot. Can be anything of your choice.
purpose	String	NO	The purpose of the bot. Can be anything of your choice.
status	enabled/disabled	NO	The current working status of the bot.

Curl Request

curl --location 'UCI_API_BASE_URL/admin/bot' \
--header 'Authorization: YOUR_JWT_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "startingMessage": "start test bot",
    "name": "TestBotName",
    "startDate": "2024-01-20",
    "endDate": "2026-09-20",
    "logic": "3f0c937a-a961-42db-a5cd-c17f3b417b5c",
    "users": "ce6afffa-1d5f-4748-8f25-37a1d9caa91b",
    "description": "Description of this bot",
    "purpose": "Purpose of this bot",
    "status": "enabled"
}'

After creating a bot you will get a bot id as a response. Store this id somewhere and follow the steps described in the specific channel + provider guide to configure your bot here.

note

Prerequisites​

Setting Secret Credentials​

Headers

Request Body

Curl Request

note

Setup Adapter​

Headers

Request Body

Attention

Curl Request

note

Setup Transformer​

Headers

Request Body

Curl Request

note

Setup Conversation Logic​

Headers

Request Body

Curl Request

note

Setup User Segment (Optional)​

Prerequisite​

Headers

Request Body

Curl Request

note

Creating a Bot​

Headers

Request Body

Curl Request

Contents

Prerequisites

Setting Secret Credentials

Setup Adapter

Setup Transformer

Setup Conversation Logic

Setup User Segment (Optional)

Prerequisite

Creating a Bot