Bring Your Own Voice Adapter

Write Your Own Voice Adapter

Partner need to execute following steps to integrate their voice adapter with platform -

1. Create Voice Provider Resource

First, register voice provider with voice adapter urls by creating an instance of voice provider resource under CCaaS Partner Id

Request:

POST /partners/{{CCaaS-Partner-ID}}/voiceproviders
Host: {{BASE_URL}}
Content-Type: application/json
Authorization: Basic {{Client-ID}}:{{Secret}}
x-resource-template-version: {{template-version}}

{
  "name": "unique name of voice provider",
  "accept_call_url": "adapter url to accept call from softphone",
  "end_call_url": "adapter url to end call from softphone",
  "hold_call_url": "adapter url to hold call from softphone",
  "resume_call_url": "adapter url to resume call from softphone",
  "mute_call_url": "adapter url to mute call from softphone",
  "unmute_call_url": "adapter url to unmute call from softphone",
  "access_token_url": "adapter url to generate token for voice provider client"
}

The HTTP response should provide you the id of the new voice provider resource created.

Response:

{
    "id": "394e3814-7562-4f25-a854-2b74e91ad15a"
}

2. Associate Voice Provider with Phone Number

Next, associate existing Toll Free Number (TFN) with voice provider resource created above. This is required to identify voice adapter url handling the calls received by a TFN.

Request:

POST /partners/{{CCaaS-Partner-ID}}/phonenumbers/{{Phone-Number-ID}}
Host: {{BASE_URL}}
Content-Type: application/json
Authorization: Basic {{Client-ID}}:{{Secret}}
x-resource-template-version: {{template-version}}

{
  "voice_provider_id_resource_uri": "/partners/{{CCaaS-Partner-ID}}/voiceproviders/{{Voice-Provider-ID}}"
}

3. Create Channel Resource

A channel is an application client through which end-users can send and receive messages with other Participants over a Conversation.

Learn to create your custom channel to process Conversation Events in the tutorial describing how to set up a Channel.

4. Webhook

A Conversation Event is a callback to a webhook endpoint on voice adapter notifying that an action has occurred. Events occur when a Participant has joined or left a Conversation; a Participant sent a Conversation Message; a Participant closed a Conversation, etc.

To learn more about Conversation Events, see the Conversation webhook events

4. APIs

Following APIs of voice adapter are consume by softphone for different purposes like accept inbound call, hold participant, remove participant, etc.

1. Accept Call

Softphone calls this api when agent receives a request to accept inbound call. Once operation is successful, adapter is expected to publish kafka event PARTICIPANTCALLINITIATED for agent participant.

Request:

Method: POST
Content-Type: application/json

{
  "conversationId": "5a974dd7-475a-41c0-a027-bfdf09627b13",
  "author": {
    "userName": "testAgent",
    "participantId": "4a70a876-bf90-4360-92c3-0edd7463c691",
  } 
}

Response:

{
    "status": "Success"
}

2. End Call

Softphone calls this api when agent clicks on end call button to terminate call of all participants or to end their call only. Once operation is successful, adapter is expected to publish kafka event PARTICIPANTCALLCOMPLETED for agent participant.

Request:

Method: POST
Content-Type: application/json

{
  "conversationId": "5a974dd7-475a-41c0-a027-bfdf09627b13",
  "removeAllParticipants": false,
  "participantId": "6e312815-2d32-409b-9c57-f9e79e7baf49",
  "author": {
    "userName": "testAgent",
    "participantId": "4a70a876-bf90-4360-92c3-0edd7463c691",
  } 
}

Response:

{
    "status": "Success"
}

3. Hold Call

Softphone calls this api when agent clicks on hold call on one of active participants of call.

Request:

Method: POST
Content-Type: application/json

{
  "conversationId": "5a974dd7-475a-41c0-a027-bfdf09627b13",
  "participantId": "6e312815-2d32-409b-9c57-f9e79e7baf49",
  "author": {
    "userName": "testAgent",
    "participantId": "4a70a876-bf90-4360-92c3-0edd7463c691",
  } 
}

Response:

{
    "status": "Success"
}

4. Resume Call

Softphone calls this api when agent clicks on resume call on a participant who is already on hold.

Request:

Method: POST
Content-Type: application/json

{
  "conversationId": "5a974dd7-475a-41c0-a027-bfdf09627b13",
  "participantId": "6e312815-2d32-409b-9c57-f9e79e7baf49",
  "author": {
    "userName": "testAgent",
    "participantId": "4a70a876-bf90-4360-92c3-0edd7463c691",
  } 
}

Response:

{
    "status": "Success"
}

5. Generate Token for voice provider client

To initialize voice provider client, it needs a JWT token to authenticate and authorize softphone with voice provider.

Request:

Method: POST
Content-Type: application/json

{
  "agentLogonName": "testAgent"
}

Response:

{
    "token": "dasdgdfhfhgjnguhk"
}

Bring Your Own Voice Adapter

Write Your Own Voice Adapter

1. Create Voice Provider Resource

2. Associate Voice Provider with Phone Number

3. Create Channel Resource

4. Webhook

4. APIs

1. Accept Call

2. End Call

3. Hold Call

4. Resume Call

5. Generate Token for voice provider client

On this page