Integration with a Chatbot using Sangoma CX WebChat Widget as Front-End
- Alfredo Gonzalez
Introduction
Description: This section details how to build a chatbot application by using the Sangoma CX WebChat widget, becoming the user interface for the end-customer to interact with the chatbot. We will use the Sangoma Digital Interactions API to handle the backend logic to communicate/integrate with the chatbot.
scope: cx.digital-interactions
Integration Flow
Note: In the API Request sections, replace <YOUR_ACCESS_TOKEN> your Access Token obtained from the Requesting Access Token authentication step detailed in API Authentication .
1. Create the agent bot
To receive events from Sangoma CX, you need to set up a agent bot. This requires a publicly accessible FQDN. For development purposes, you can use a tool like ngrok. We will use the outgoing_url to send webhook events. Confirm this is publicly accessible.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/agents-bot/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"outgoing_url": "<your webhook fqdn>",
"description": "test",
"name": "My first bot"
}'2. Choosing an Inbox
You can choose which inbox your chatbot is “assigned” to. In order to list the inboxes you can use the following request.
API Request
curl --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/inboxes/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'3. Assigning the agent bot to the inbox
After choosing the inbox, you should assign the agent bot to that inbox using the following request.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/agents-bot/assign/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"inbox_id": "<inbox_id>",
"agent_bot_id": "<agent_bot_id>"
}'Now you can start your conversation using the web widget.
4. Sending Messages
Once the conversation is created, you can start sending messages.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/messages/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"is_bot": true,
"agent_bot_id": <agentbot_id>,
"tenant_domain": "acme.cx.sangoma.com",
"content": "My message",
"message_type": "outgoing",
"conversation_id": <conversation.id>
}'6. Redirect to a Customer Representative
If the customer needs human assistance, redirect the conversation to an inbox with agents that will interact with the customer.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/conversations/deliver-to-agent/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"conversation_id": <conversation.id>
}'7. Finish the Conversation
When the customer is satisfied with the bot assistance and does not require involving an agent to interact with the customer, finish the conversation using the followin API.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/conversations/finish/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"conversation_id": <conversation.id>
}'