Skip to content

Latest commit

 

History

History
333 lines (286 loc) · 15.5 KB

whatsapp-flow-for-uci.md

File metadata and controls

333 lines (286 loc) · 15.5 KB

Whatsapp Flow (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.