Introduction
Description: Makes an outbound call to a specific destination on behalf of an Agent logged into CX. Supports any Agent CX extension type.
scope: cx.agent-calls
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/agents/call/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"agent_name": "agent.test",
"destination": "9001",
"tenant_domain": "acme.cx.sangoma.com"
}'
Note: Replace <YOUR_ACCESS_TOKEN> with your Access Token obtained from the authentication step.
This API call will enable the specified agent (agent_name) within the tenant_domain to make calls to the provided destination.
Placing a Call from a Queue to a Destination
scope: cx.queue-calls
You can place a call - initiated as Outbound - to a specific destination and, when answered, it will be treated as a regular Inbound Queue Call, waiting in the Queue to be answered by an agent.
API Request
curl -XPOST --location 'https://cpaas.sangoma.com/cx/api/v1/queues/call/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{
"queue_name": "queue_test",
"destination": "9001",
"tenant_domain": "acme.cx.sangoma.com"
}'
Note: Replace <YOUR_ACCESS_TOKEN> with your Access Token obtained from the authentication step.
This API call will enable the specified Queue (queue_name) within the tenant_domain to make calls to the provided destination.
For detailed instructions on using our supported helper libraries or SDKs, refer to the quickstart guides for:
Node.js SDK (example app link)
Creating a Agent Chatbot using Sangoma Digital Interactions API (Our Widget)
scope: cx.digital-interactions
In this section, we will build a chatbot application using a inbox 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 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, so certify that this is public 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 attached to. In order to list the inboxes you can use the following request.
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>'
3. Attaching the agent bot to the inbox
After choose the inbox, you should attach 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. 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>
}'
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)