...
| Code Block |
|---|
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
| Code Block |
|---|
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
| Code Block |
|---|
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
| Code Block |
|---|
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
| Code Block |
|---|
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
| Code Block |
|---|
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
| Code Block |
|---|
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 with agents that will interact with the customer representative.
API Request
| Code Block |
|---|
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 assistanceassistance and does not require involving an agent to interact with the customer, finish the conversation using the followin API.
API Request
| Code Block |
|---|
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:
...