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

• Here is a Sample ODK Excel Form 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 (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.

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, 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"
}