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/agent-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>",
"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/assign-agent-bot/' \
--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 '{
"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>
}'
Advanced: Creating a Chatbot and Web Widget using Sangoma Digital Interactions API (Self Widget)
scope: cx.digital-interactions
In this section, we will build a chatbot application consisting of a web widget that starts a conversation on your front panel. We will use the Sangoma Digital Interactions API to handle the backend logic for this chatbot.
1. Create a Webhook
To receive events from Sangoma CX, you need to set up a webhook. This requires a publicly accessible FQDN. For development purposes, you can use a tool like ngrok.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/webhooks/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"url": "<your webhook fqdn>",
"subscriptions": [
"conversation_created",
"message_created"
]
}'
2. Choosing an Inbox
You can choose whether your chatbot will use a unique inbox or if the customer can choose one. This is useful for creating different flows based on the selected inbox.
List Inboxes
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>'
If you are using only one inbox, you can hard-code the value to save a request. Find the inbox ID in the interface: Sangoma Call Center Inbox
3. Create a Contact for Your Customer
With the inbox ID, create a contact for the customer after collecting basic data such as name, email, and phone number.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/contacts/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"name": "My Customer Name",
"email": "my@customer.email",
"inbox_id": <inbox_id>,
"phone_number": "+199999999"
}'
4. Start the Conversation
After creating the contact, initiate a conversation on the platform.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/digital-interactions/conversations/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"tenant_domain": "acme.cx.sangoma.com",
"source_id": "<contact.email>",
"contact_id": <contact.id>,
"inbox_id": <inbox_id>,
"priority": <priority_int>,
"initial_message": "Hello world"
}'
5. 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 '{
"tenant_domain": "acme.cx.sangoma.com",
"content": "My message",
"message_type": "incoming|outgoing",
"conversation_id": <conversation.id>
}'
Note: If the message_type is outgoing, it will be presented as a bot message; if incoming, it will be a customer message. The default value is outgoing.
6. Deliver to a Customer Representative
If the customer needs human assistance, redirect the conversation to an inbox customer representative.
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 or representative's assistance, finish the conversation using the 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>
}'
For step-by-step instructions on how to do this with one of our supported helper libraries or SDKs, check out the quickstarts for:
Node.js SDK (example app link)