> For the complete documentation index, see [llms.txt](https://uci.sunbird.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://uci.sunbird.org/use/developer/api-documentation/bot-setup-apis.md).

# Bot Setup APIs

## 1. Overview

UCI provides a list of apis that will help you to configure bots for conversation or broadcasting.

## 2. APIs

To setup a bot and start conversation with users, the following steps need to be followed.

### 2.1 Add adapter

Add a new adapter for the available channel & providers. Below is a list of available parameters.

* **name:** Name of the adapter
* **channel**: Messaging channel.
* **provider**: Message provider
* **config**:
  * **credentials**:
    * **vault**: Vault service name, Default value: samagra
    * **variable**: Variable name added in the vault.

List of available channel and provider combinations:

* provider: netcore, channel: whatsapp
* provider: gupshup, channel: whatsapp
* provider: gupshup, channel: sms
* provider: cdac, channel: sms
* provider: firebase, channel: web

Note: If you need some other channel or provider, contribute a new adapter for the same. [Click here](/use/developer/contribution-guide/create-an-adapter.md) to see how to do this.

Below is a curl request for adding a new adapter in db. This adapter will be associated with a bot to determine the channel and provider for the bot when conversing.

```
curl --location --request POST 'http://UCI_API:PORT/admin/adapter' \
    --header 'admin-token: {ADMIN_TOKEN}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "data": {
            "name": "UCI Gupshup Whatsapp",
            "channel": "whatsapp",
            "provider": "gupshup",
            "config": {
                "credentials": {
                    "vault": "samagra",
                    "variable": "uci-gupshup-whatsapp"
                }
            }
        }
    }'  
```

This API will create a new adapter and will return the adapter id (Eg. 2a704e82-132e-41f2-9746-83e74550d2ea). We can use this adapter id later in [create conversation logic](#2.4-Add-a-Conversation-Logic) api.

### 2.2 Creating a Conversation Bot

A conversation bot is used to communicate with the user one on one. A chatbot uses a flow defined in an odk xml form to chat with a user. The steps for creating a simple conversation chatbot are given below.

### 2.2.1 Upload ODK Form

For using ODK transformer, we will first have to upload a ODK form. Follow below steps to upload a ODK form.

* Convert a ODK Excel form to XML form using [Link](https://getodk.org/xlsform/).
* Here is a [Sample ODK Excel Form](https://github.com/samagra-comms/docker-deploy/blob/main/media/List-QRB-Test-Bot.xlsx) for reference.
* Upload this XML from using this api.

  ```
  curl --location 'http://UCI_API:PORT/admin/form/upload' \
  --header 'admin-token: {ADMIN_TOKEN}' \
  --form 'form=@"{PATH_TO_YOUR_XML}"' \
  --form 'mediaFiles=@"{PATH_TO_YOUR_MEDIA_1}"' \
  --form 'mediaFiles=@"{PATH_TO_YOUR_MEDIA_2}"' \
  --form 'mediaFiles=@"{PATH_TO_YOUR_MEDIA_N}"'
  ```

  **Response**: The API will return a form id. Use this form id to create conversation logic API. Form id E.g. **testing\_form**

  ```
  {
      "apiId": "api.form.upload",
      "path": "/admin/form/upload",
      "msgid": "fec3421b-cc04-42e2-9ce9-e004b3ded827",
      "result": {
          "status": "UPLOADED",
          "data": {
              "formID": "testing_form"
          }
      },
      "startTime": "2023-07-04T12:01:00.268Z",
      "method": "POST",
      "endTime": "2023-07-04T12:01:21.785Z"
  }
  ```

### 2.2.2 Add a Conversation Logic

For any bot we will have to specify a certain configuration which is a part of conversation logic. Below is a list of available parameters.

* **name:** Conversation logic unique name
  * **transformers:** Array of transformers
    * **id:** id of transformer
    * **meta:**
      * **formID:** uploaded odk form id from [upload form api](#2.2-upload-odk-form) (For ODK transformer)
      * **params:** Array of parameters to be used in template \*\*\*\* message (For Broadcast transformer)
      * **body:** (For Broadcast transformer)
      * **type:** type of template (For Broadcast transformer), Default. **JS\_TEMPLATE\_LITERALS**
    * **type:** type of transformers (Eg. broadcast/generic) \*\*\*\*
  * **adapter:** id \*\*\*\* of adapter from [add adapter api](#2.1-add-adapter).

Use below curl to create a conversation logic.

```
curl --location 'http://UCI_API:PORT/admin/conversationLogic' \
--header 'asset: conversationLogic' \
--header 'admin-token: dR67yAkMAqW5P9xk6DDJnfn6KbD4EJFVpmPEjuZMq44jJGcj65' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/plain, */*' \
--header 'ownerOrgID: org01' \
--header 'ownerID: 8f7ee860-0163-4229-9d2a-01cef53145ba' \
--data '{
    "data": {
        "name": "TEST",
        "description": "TEST",
        "transformers": [
            {
                "id": "774cd134-6657-4688-85f6-6338e2323dde",
                "meta": {
                    "form": "https://hosted.my.form.here.com",
                    "formID": "testing_form",
                    "title": "TEST",
                    "body": "TEST",
                    "serviceClass": "SurveyService",
                    "hiddenFields": [
                        {
                            "name": "mobilePhone",
                            "path": "mobilePhone",
                            "type": "param",
                            "config": {
                                "dataObjName": "user"
                            }
                        }
                    ],
                    "templateType": "JS_TEMPLATE_LITERALS",
                    "type": "broadcast"
                }
            }
        ],
        "adapter": "6efa8087-0939-49ab-b8e5-5676e036c17b"
    }
}'
```

**Response**: It will return a conversation logic id, use it in create bot. Eg. **be37c9f2-7f2b-4e19-b525-33b0a2aabdd5**

```
{
    "apiId": "api.admin.conversationLogic",
    "path": "/admin/conversationLogic",
    "msgid": "df8edb08-f887-41cd-8f7a-604d3229dabc",
    "result": {
        "id": "be37c9f2-7f2b-4e19-b525-33b0a2aabdd5",
        "name": "TEST",
        "createdAt": "2023-07-05T05:29:57.310Z",
        "updatedAt": "2023-07-05T05:29:57.311Z",
        "description": null,
        "adapterId": "6efa8087-0939-49ab-b8e5-5676e036c17b"
    },
    "startTime": "2023-07-05T05:29:57.293Z",
    "method": "POST",
    "ownerId": "8f7ee860-0163-4229-9d2a-01cef53145ba",
    "endTime": "2023-07-05T05:29:57.314Z"
}
```

### 2.2.3 Configure a bot

After the conversation logic is defined, we can use this to create a new bot. This bot must include a starting message as we will use this to start a conversation for this bot. Below is a list of available parameters.

* **startingMessage:** unique message to start conversation.
* **name:** unique name of bot.
* **users:** array of user segment ids, currently the first one will be used.
* **logic:** array of conversation logic ids from add logic api, currently the first one will be used.
* **status:** status of bot, Eg. draft/disabled/enabled.
* **startDate:** date from which bot will be active.
* **endDate:** date till which bot will be active.

Use below curl to create a conversation logic.

```
curl --location --request POST 'http://UCI_API:PORT/admin/bot' \
--header 'admin-token: {ADMIN_TOKEN}' \
--form 'botImage=@"/path/to/file"' \
--form 'data="{
    \"data\": {
        \"startingMessage\": \"Hi Bot\",
        \"name\": "UCI Demo Bot\",
        \"users\": [],
        \"logic\": [\"be37c9f2-7f2b-4e19-b525-33b0a2aabdd5\"],
        \"status\": \"enabled\",
        \"startDate\": \"2023-05-4\",
        \"endDate\": \"2025-12-01\"
    }
}"'
```

Response: This api will return a bot id & other bot information. Use the starting message (Eg. Hi Bot) from here to start a conversation with a bot.

### 2.3 Creating a Broadcast Bot (Optional)

### 2.3.1 Add a User Segment

User segment contains the group of users to whom the broadcast would be sent out to.

Use the curl below to create a user segment.

```
curl --location 'http://UCI_API:PORT/admin/user-segment' \
--header 'asset: userSegment' \
--header 'admin-token: {ADMIN_TOKEN}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/plain, */*' \
--header 'ownerOrgID: org01' \
--header 'ownerID: 8f7ee860-0163-4229-9d2a-01cef53145ba' \
--data '{
    "name": "TEST_USER_SEGMENT",
    "all": {
        "type": "get",
        "config": {
            "url": "http://testSegmentUrl/segments/1/mentors?deepLink=nipunlakshya",
            "type": "GET",
            "cadence": {
                "perPage": 100,
                "retries": 5,
                "timeout": 60,
                "concurrent": true,
                "pagination": true,
                "concurrency": 10,
                "retries-interval": 10
            },
            "pageParam": "page",
            "credentials": {}
        }
    },
    "byID": {
        "type": "get",
        "config": {
            "url": "http://testSegmentUrl/segments/1/mentors?deepLink=nipunlakshya://chatbot",
            "type": "GET",
            "cadence": {
                "perPage": 100,
                "retries": 5,
                "timeout": 60,
                "concurrent": true,
                "pagination": true,
                "concurrency": 10,
                "retries-interval": 10
            },
            "pageParam": "page",
            "credentials": {}
        }
    },
    "byPhone": {
        "type": "get",
        "config": {
            "url": "http://testSegmentUrl/segments/1/mentors?deepLink=nipunlakshya://chatbot",
            "type": "GET",
            "cadence": {
                "perPage": 100,
                "retries": 5,
                "timeout": 60,
                "concurrent": true,
                "pagination": true,
                "concurrency": 10,
                "retries-interval": 10
            },
            "pageParam": "page",
            "credentials": {}
        }
    }
}'
```

**Response**: It will return a response containing the id of the segment that is created. Eg. **2ddea169-2db9-442b-99f2-fc85c9ea1a02**

```
{
    "id": "2ddea169-2db9-442b-99f2-fc85c9ea1a02",
    "createdAt": "2023-07-05T06:02:16.285Z",
    "updatedAt": "2023-07-05T06:02:16.285Z",
    "name": "TEST_JUL_5",
    "description": null,
    "count": 0,
    "category": null,
    "allServiceID": "00b775e2-fae9-439f-8e9d-3231dc5aed46",
    "byPhoneServiceID": "a279516d-3730-4b7f-b74c-de5df0206177",
    "byIDServiceID": null,
    "botId": null
}
```

### 2.2.4 Add a Broadcast bot

After the conversation logic is defined, we can use this to create a new bot. This bot must include a starting message as we will use this to start a conversation for this bot. Below is a list of available parameters.

* **startingMessage:** unique message to start conversation
* **name:** unique name of bot \*\*\*\*
* **users:** array of user segment ids, currently the first one will be used
* **logic:** array of conversation logic ids from [add logic api](#2.3-create-a-conversation-logic), currently the first one will be used
* **status:** status of bot, Eg. draft/enabled
* **startDate:** date from which bot will be active
* **endDate:** date till which bot will be active

Use below curl to create a conversation logic.

```
curl --location 'http://http//UCI_API:PORT/admin/bot' \
--header 'asset: bot' \
--header 'admin-token: dR67yAkMAqW5P9xk6DDJnfn6KbD4EJFVpmPEjuZMq44jJGcj65' \
--header 'Accept: application/json, text/plain, */*' \
--header 'ownerOrgID: org01' \
--header 'ownerID: 8f7ee860-0163-4229-9d2a-01cef53145ba' \
--form 'botImage=@"{PATH_TO_IMAGE}"' \
--form 'data="{
    \"data\": {
    \"name\": \"TEST BROADCAST BOT\",
    \"description\": \"TEST\",
    \"purpose\": \"TEST\",
    \"startingMessage\": \"Hi Test Broadcast\",
    \"startDate\": \"2023-06-16\",
    \"endDate\": \"2023-06-30\",
    \"isBroadcastBotEnabled\": true,
    \"segmentId\": \"1\",
    \"status\": \"enabled\",
    \"users\": [
        \"2ddea169-2db9-442b-99f2-fc85c9ea1a02\" // Get this id from user segment api response
    ],
    \"logic\": [
      \"be37c9f2-7f2b-4e19-b525-33b0a2aabdd5\" // Get this id from conversation logic api response
    ]
  }
}"'
```

**Response**: This api will return a bot id & other bot information. Use the starting message (Eg. **Hi Test ODK**) from here to start conversation with a bot.

```
{
    "apiId": "api.admin.bot",
    "path": "/admin/bot",
    "apiVersion": "v1",
    "msgid": "ba858dbb-8710-40e3-9fca-e8f928ff2cfc",
    "result": {
        "id": "5066c217-6ae0-4e3c-9802-8c0cce660c2b",
        "createdAt": "2023-07-04T12:59:48.804Z",
        "updatedAt": "2023-07-04T12:59:48.804Z",
        "name": "TEST ODK BROADCAST",
        "startingMessage": "Hi Test Broadcast",
        "ownerID": null,
        "ownerOrgID": null,
        "purpose": null,
        "description": null,
        "startDate": "2023-06-15T00:00:00.000Z",
        "endDate": "2025-12-01T00:00:00.000Z",
        "status": "ENABLED",
        "tags": [],
        "botImage": "1c8516c6-c4c3-4a37-a8dd-89109e8e0e60.png"
    },
    "startTime": "2023-07-04T12:59:48.265Z",
    "method": "POST",
    "endTime": "2023-07-04T12:59:49.097Z"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://uci.sunbird.org/use/developer/api-documentation/bot-setup-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.