Whatsapp (Netcore)

Environment Variables Required

• NETCORE_WHATSAPP_AUTH_TOKEN

• NETCORE_WHATSAPP_SOURCE

• NETCORE_WHATSAPP_URI

In order to test out the whatsapp flow, you need to provide these to the installation script while setting up UCI. Refer to the docs here

Types of Bots:

1. Broadcast Bot: This type of bot is used to send a single message to a large group of people. It doesn't expect a reply to the message.

2. Conversation Bot: This type of bot is designed for a two way conversation with a user. The conversation is regulated by an ODK form.

Broadcast Flow

This is a 4 step process.

1. Create conversation logic:

curl --location 'http://localhost:3002/admin/conversationLogic' \
--header 'admin-token: 4737ea8520bd454caabb7cb3d36e14bc1832c0d3f70a4189b82598670f11b1bd' \
--header 'Content-Type: application/json' \
--header 'Cookie: fusionauth.locale=en_US; fusionauth.sso=AgOat0GjncGOHhPpH_HuL9QQqnfMitd15O-ofS-uTcdA' \
--data '{
    "data": {
        "id": null,
        "name": "Netcore Demo",
        "description": "Netcore Demo",
        "transformers": [
            {
                "id": "774cd134-6657-4688-85f6-6338e2323dde",
                "meta": {
                    "body": "Hello ${name}-${phoneNo}, Netcore Test Notification Body demo dry run.",
                    "type": "broadcast",
                    "title": "Netcore Demo",
                    "params": [
                        "name",
                        "phoneNo"
                    ],
                    "templateType": "JS_TEMPLATE_LITERALS"
                }
            }
        ],
        "adapter": "44a9df72-3d7a-4ece-94c5-98cf26307323"
    }
}'

Parameter	Description
id	The ID of the conversation logic.
name	The name of the conversation logic.
description	The description of the conversation logic.
transformers	An array of transformer objects that define the message content and behavior.
	- id: The ID of the transformer.
	- meta: An object containing metadata about the transformer.
	- body: The message content.
	- type: The type of message, e.g., "broadcast".
	- title: The title of the message.
	- params: An array of parameter names used in the message template.
	- templateType: The template type, e.g., "JS_TEMPLATE_LITERALS".
adapter	The ID of the adapter associated with the conversation logic.

This will create a conversation logic for the broadcast flow. We don't need an ODK form here as this is not a two-way conversation flow that is driven by ODK logic. The conversation logic for this type of bot only has a single broadcast message which is defined in the meta of the request.

1. Create user segment:

Creating a user segment is analogous to importing a list of users into UCI. The curl for this is given below.

curl --location 'http://localhost:3002/admin/user-segment' \
--header 'admin-token: 4737ea8520bd454caabb7cb3d36e14bc1832c0d3f70a4189b82598670f11b1bd' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Netcore demo",
    "all": {
        "type": "get",
        "config": {
            "url": "http://localhost:9080/service/testUserSegment2",
            "type": "GET",
            "cadence": {
                "perPage": 1,
                "retries": 5,
                "timeout": 60,
                "concurrent": true,
                "pagination": true,
                "concurrency": 10,
                "retries-interval": 10
            },
            "pageParam": "page",
            "credentials": {},
            "totalRecords": 1
        }
    },
    "byID": {
        "type": "get",
        "config": {
            "url": "http://localhost:9080/service/testUserSegment2",
            "type": "GET",
            "cadence": {
                "perPage": 1,
                "retries": 5,
                "timeout": 60,
                "concurrent": true,
                "pagination": true,
                "concurrency": 10,
                "retries-interval": 10
            },
            "pageParam": "page",
            "credentials": {},
            "totalRecords": 1
        }
    },
    "byPhone": {
        "type": "get",
        "config": {
            "url": "http://localhost:9080/service/testUserSegment2",
            "type": "GET",
            "cadence": {
                "perPage": 1,
                "retries": 5,
                "timeout": 60,
                "concurrent": true,
                "pagination": true,
                "concurrency": 10,
                "retries-interval": 10
            },
            "pageParam": "page",
            "credentials": {},
            "totalRecords": 1
        }
    },
    "count": 0
}'

This creates a new user segment with the user list provided on http://localhost:9080/service/testUserSegment2.

Parameter	Description
name	The name of the user segment.
all	Configuration for retrieving all users in the segment.
	- type: Type of HTTP request (e.g., "get") for retrieving users.
	- config: An object containing configuration settings for the HTTP request.
	- url: The URL to which the HTTP request will be sent to retrieve user data.
	- type: The type of HTTP request (e.g., "GET").
	- cadence: An object containing settings related to timing and concurrency of the requests.
	- pageParam: The parameter name used for pagination in the URL's query parameters.
	- credentials: An object containing credentials (if required) for making the request.
	- totalRecords: A field indicating the total number of records in the user segment.
byID	Configuration for retrieving users by their IDs.
byPhone	Configuration for retrieving users by their phone numbers.
count	A field indicating the count of users in the user segment.

The user list on the provided URL should be in the following format:

{
  "data": [
    {
      "phoneNo": "<PHONE_NUMBER>",
      "name": "<USER_NAME>",
    }
  ]
}

Parameter	Description
data.phoneNo	The phone number of the user.
data.name	The name of the user.

These params are necessary for the flow to work. Apart from these params, any additional params which are defined while creating conversation logic should also be provided in this object.

Note:

This user list definition is only valid for Whatsapp flow. Definitions will differ for different use cases.

1. Create a broadcast bot:

curl --location 'http://localhost:3002/admin/bot' \
--header 'admin-token: 4737ea8520bd454caabb7cb3d36e14bc1832c0d3f70a4189b82598670f11b1bd' \
--form 'botImage=@"/home/ryanwalker277/Pictures/Screenshot from 2023-08-08 15-10-09.png"' \
--form 'data="{
    \"data\": {
        \"startingMessage\": \"Hi Netcore demo\",
        \"name\": \"Hi Netcore demo\",
        \"users\": [\"1be4e149-3618-4135-84ac-f39c49d6f671\"],
        \"logic\": [
            \"2b16fd7b-6c87-4726-9035-c20400901a82\"
        ],
        \"status\": \"enabled\",
        \"startDate\": \"2023-03-01\",
        \"endDate\": \"2024-12-01\",
        \"ownerid\":\"8f7ee860-0163-4229-9d2a-01cef53145ba\",
        \"ownerorgid\":\"org01\",
        \"purpose\":\"Testing\",
        \"desc\":\"Netcore Broadcast Bot Desc\"
    }
}"'

Parameter	Description
botImage	The image file of the bot to be uploaded.
data	A JSON object containing various configuration settings for the bot.
data.startingMessage	The initial message of the bot to trigger the conversation flow.
data.name	The name of the bot.
data.users	An array of user segments attached to the bot
data.logic	Conversation logic associated with the bot.
data.status	The status of the bot ("enabled" or "disabled").
data.startDate	The start date of the bot's activity.
data.endDate	The end date of the bot's activity.
data.ownerid	The ID of the bot's owner. (Vault)
data.ownerorgid	The organization ID of the bot's owner. (Vault)
data.purpose	A description of the purpose of the bot.
data.desc	A description of the bot.

At the time of bot creation, it must be attached to a user segment. This is done by passing the segment id, which is a unique identifier for the user segement created in the previous step, in the users section of the request body. The segment id can be obtained from the response of the previous step. Add the conversation logic id to the body in logic section.

1. Triggering the bot:

curl --location  'http://localhost:3002/campaign/start?campaignId=859ed55f-c276-4f38-ba72-5f08e1733705'

Replace the campaignId with the bot id given by the bot creation api.This will trigger a broadcast notification for all the users in that segment over whatsapp.

Conversation Flow:

This is a 3 step process.

1. Upload ODK form:

curl --location 'http://localhost:3002/admin/form/upload' \
--header 'ownerId: 8f7ee860-0163-4229-9d2a-01cef53145ba' \
--header 'ownerOrgId: org1' \
--header 'admin-token: 4737ea8520bd454caabb7cb3d36e14bc1832c0d3f70a4189b82598670f11b1bd' \
--form 'form=@"/home/ryanwalker277/Music/WhatsappDemo/SampleOdkForm.xml"'

Parameter	Description
ownerID	The ID of the owner of the form. (Vault)
ownerOrgId	The organization ID of the owner of the form. (Vault)
admin-token	The admin token for authentication.
form	The XML file of the form to be uploaded.

Refrence to create an ODK Form

In the conversation logic, ODK form becomes necessary as the whole conversation flow is determined by this.

1. Create conversation logic:

curl --location 'http://localhost:3002/admin/conversationLogic' \
--header 'admin-token: 4737ea8520bd454caabb7cb3d36e14bc1832c0d3f70a4189b82598670f11b1bd' \
--header 'Content-Type: application/json' \
--header 'Cookie: fusionauth.locale=en_US; fusionauth.sso=AgOat0GjncGOHhPpH_HuL9QQqnfMitd15O-ofS-uTcdA' \
--data '{
    "data": {
        "id": null,
        "name": "Netcore Demo",
        "description": "Necore Desc",
        "transformers": [
            {
                "id": "bbf56981-b8c9-40e9-8067-468c2c753659",
                "meta": {
                    "form": "https://hosted.my.form.here.com",
                    "formID": "List-Button-test-v5"
                }
            }
        ],
        "adapter": "44a9df72-3d7a-4ece-94c5-98cf26307323"
    }
}'

Parameter	Description
data	An object containing the conversation logic data.
data.id	The ID of the conversation logic (null for new).
data.name	The name of the conversation logic.
data.description	The description of the conversation logic.
data.transformers.id	The ID of the transformer.
data.transformers.meta	An object containing metadata about the transformer.
data.transformers.meta.form	The URL of the form associated with the transformer.
data.transformers.meta.formID	The ID of the form associated with the transformer.
data.adapter	The ID of the adapter associated with the logic.

Replace the formId with the id of the form uploaded. This returns a unique conversation logic id.

1. Create conversation bot:

curl --location 'http://localhost:3002/admin/bot' \
--header 'admin-token: 4737ea8520bd454caabb7cb3d36e14bc1832c0d3f70a4189b82598670f11b1bd' \
--form 'botImage=@"/home/ryanwalker277/Music/WhatsappDemo/boticon.jpeg"' \
--form 'data="{
    \"data\": {
        \"startingMessage\": \"Hi uci\",
        \"name\": \"Netcore Demo\" ,
        \"users\": [],
        \"logic\": [\"38dde1ef-d618-4440-adc7-34a7df885187\"],
        \"status\": \"enabled\",
        \"startDate\": \"2023-05-4\",
        \"endDate\": \"2025-12-01\"
    }
}"'

Parameter	Description
botImage	The image file of the bot to be uploaded.
data	An object containing the bot data.
data.startingMessage	The initial message of the bot.
data.name	The name of the bot.
data.users	An array of user IDs associated with the bot.
data.logic	Conversation logic associated with the bot.
data.status	The status of the bot ("enabled" or "disabled").
data.startDate	The start date of the bot's activity.
data.endDate	The end date of the bot's activity.
botImage	The image file to be uploaded as the bot's image.

Notice that we are not passing the segment id here. That means this bot is not attached to any user segment. So, any user can interact with this bot by sending the starting message.