Introduction
Description: This section details how to build a chatbot application by using a third-party WebChat widget that represents the user interface for the end-customer to interact with the chatbot or Sangoma CX Agent. We will use the Sangoma Digital Interactions API to handle the logic to communicate/integrate with the chatbot or 3rd party WebChat widget.
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 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 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. Create a Contact for Your Customer
With the inbox ID, and before initiating the Chat Conversation 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. Redirect 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>
}'