Page Comparison

Those APIs are open to our end customers through CPaaS.

Base URL

All URLs referenced in the documentation (except for Authentication) have the following base:

https://cpaas.sangoma.com/cx/

The authentication section must use this base:

https://auth.sangoma.com/

The Sangoma REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Authentication

HTTP requests to the REST API are protected with a Bearer Token (OAuth). In summary, you will utilize your Sangoma Basic token to obtain an Access Token for using our APIs. The Access Token has a one-year expiration.

Requesting a Basic Token

Go to System > Configuration > CPaaS Credentials

Click in the ADD CREDENTIALS button

...

You should receive your new Client ID and Client Secret

...

This info is needed for the next request in order to receive a OAuth token.

The CPaaS Credentials settings will only be accessible and fully functional if your tenant has been properly setup with a CPaaS Account UUID. For existing production customers, this tenant information should be automatically backfilled by CX, so they usually won’t need to worry about this requirement. If you’re executing this feature on QA and staging environments, you might need to manually populate this tenant field on the tenant administration / root tenant.

Requesting Access Token

To obtain an Access Token, use the /oauth/token endpoint and include your Basic Token in the Authorization header.

Code Block

curl --location 'https://auth.sangoma.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--basic --user <client id>:<client_secret> \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=<api scopes separated by blank spaces>'

Replace <YOUR_TOKEN> with your provided token.

If you request scope=cx.agent-calls cx.queue-calls as your API scopes, the result of this request should contains a similar payload:

Code Block
{ "access_token": "YOUR_ACCESS_TOKEN", "scope": "cx.agent-calls cx.queue-calls", "token_type": "bearer", "expires_in": 24304413 }

The access_token field is what you should use in the Authorization header for subsequent requests.

Info

You should always request for at least one API scope. You can ask for how many scopes you want, as long as their identifiers are separated by a blank space as in the example above.

An OAuth token will only grant you access to API endpoints covered by the scopes you’ve asked. You can generate as many OAuth tokens as you wish, so if you have multiple applications, you’re encouraged to generate different OAuth tokens using your Basic credentials to shrink possible attack surfaces.

Placing a Call from an Agent to a Destination

scope: cx.agent-calls

You can place a call to a specific destination using an agent logged into CX through our API.

API Request

Code Block

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

Code Block

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

Code Block

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

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>'

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

Code Block

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

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. Deliver to a Customer Representative

If the customer needs human assistance, redirect the conversation to an inbox 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>
}'

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. Deliver to a Customer Representative

If the customer needs human assistance, redirect the conversation to an inbox 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 assistance, finish the conversation using the 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:

...

The following articles detail the APIs available to build automation or integrate with the platform. All API calls require API authentification:

Child pages (Children Display)

allChildren	true

Versions Compared

Old Version 1

New Version Current

Key

Base URL

Authentication

Requesting a Basic Token

Requesting Access Token

Placing a Call from an Agent to a Destination

API Request

Placing a Call from a Queue to a Destination

API Request

Creating a Agent Chatbot using Sangoma Digital Interactions API (Our Widget)

1. Create the agent bot

API Request

2. Choosing an Inbox

List Inboxes

3. Attaching the agent bot to the inbox

API Request

4. Sending Messages

API Request

6. Deliver to a Customer Representative

API Request

Advanced: Creating a Chatbot and Web Widget using Sangoma Digital Interactions API (Self Widget)

1. Create a Webhook

API Request

2. Choosing an Inbox

List Inboxes

3. Create a Contact for Your Customer

API Request

4. Start the Conversation

API Request

5. Sending Messages

API Request

6. Deliver to a Customer Representative

API Request

7. Finish the Conversation

API Request