VoIP-inbounds

VoIP: inbounds configuration and usage example

Description

If you are not familiar with Voice over Internet Protocol, SIP or SIP trunks see the VoIP overwiev to learn about basic terms connected with this technology.

The inbound call is the frequent way of designing chat bots. Like in the case when your are building intelligence information system that is called by user.

Dasha platform provides an ability to configure inbound calls for your application. Basic Dasha application allows you to call someone, but the receiving calls requires some configurations and modificaions in SDK code. The configuring inbound telephony can be made with Dasha CLI. The dialogue model is independent and does not require any special manipulations.

This example demonstrates configuring the inbound telephony with some existing PSTN phone (SIP trunk). In our example the twillio's PSTN is used.

Also, the example shows the way of local testing the inbounds. To do this the microsip is required.

Also, explore our another demo dasha-sip-test that uses inbounds.

SDK part

Since our application is going to recieve calls, we need to create conversation queue. To configure conversation queues Dasha SDK API provides special handlers that define all main events.

Particularly, in this example we have to set the handler for the event "ready": async (id, conv, info) => { ... }. Here, id is the key of the current call, conv is the conversation object that is goind to be executed and info contains information about the received call.

Basically, this is all for SDK code.

Configuring with Dasha CLI

As you can see, the SDK part does not require any particular configuration of inbounds - we just created a queue that awaits for new conversations. The actual inbound configuration is performed via Dasha CLI.

To do that we have to use sip API (run dasha sip -h for details). Creating an inbound is connected to your account, application name and aplication groupName (default groupName is "Default").

From Dasha sip api:

dasha sip create-inbound -h
Usage: dasha sip create-inbound [options] <configName>

create an inbound SIP configuration

Options:
  --application-name <applicationName>
  --group-name <groupName>
  --ip-acls <listOfIpsWithMasks>
  --password <password>
  --ask-password
  --priority <value>                     (default: 0)
  -h, --help                            display help for command

Where

• application-name - application name specified in .dashaapp file
• group-name - name of the group used to configure call flows (same as specified when deploying the app)
• ip-acls - list of allowed IPs and networks in format ip/mask_length separated by commas (use double quotes when providing several IPs)
• password - password that will be required from user
• ask-password - pass password in cli implicitly
• priority - priority of calls in conversation queue

In our case the application name is dasha-voip-inbound-local-demo (see app/app.dashaapp). So, to create the inbound for this demo you can run the following:

dasha sip create-inbound --application-name dasha-voip-inbound-local-demo my-inbound

The result of command above:

{
  "applicationName": "dasha-voip-inbound-local-demo",
  "priority": 0,
  "groupName": "Default",
  "uri": "sip:<uuid>@sip.us.dasha.ai"
}

This uri is the one that is going to be called in future. You can always get it again running:

dasha sip list-inbound

Security

There are two options to make your application sequere:

• specifying the sip password for you inbound
• specifying the list of allowed IPs

To set the password that will be required from user, use the --password or --ask-password parameters of dasha sip create-inbound command (see the configuring section). If password is provided via SIP INVITE, then the authentification challenge begins (see SIP doc for the details).

To set the list of IPs (or networks) that are allowed to call your inbound, use the ip-acls command (see the configuring section to learn format).

https://datatracker.ietf.org/doc/html/rfc3261#section-22

Running incoming calls

If you want to be able to call your application with from some phone, you must have some phone number that is connected to sip inbound uri. To create one, you may use some external service, e.g. twilio (see sip inbound calls tutorial).

Alernatively, for testing purposes you may use microsip (see the instructions below).

Installation

1. Setup environment (see doc)
2. Run npm i in a current folder.
3. Configure inbound
4. Create a phone (sip trunk) that is connected to your inbound (see Running incoming calls)

Alternatively for local testing:

1. Download and install microsip
2. Open microsip and create the account:
   1. Right click on the bottom panel
   2. Choose "Add Account"
   3. Fill necessary fields with any letters
   4. Click "Save" button

Running the demo

1. Run npm start - this will start the application that await for incoming calls.
2. Call your application using created phone or microsip (if you use microsip, just call the sip uri from the CLI output as a phone number)

Dialogue example

{
  speaker: 'ai',
  text: 'Hello, can you hear me?',
  startTime: 2022-01-20T09:07:26.636Z,
  endTime: 2022-01-20T09:07:28.070Z
}
{
  speaker: 'human',
  text: 'yes i can',
  startTime: 2022-01-20T09:07:31.412Z,
  endTime: 2022-01-20T09:07:32.997Z
}
{
  speaker: 'ai',
  text: 'And I can hear you too. Goodbye',
  startTime: 2022-01-20T09:07:33.001Z,
  endTime: 2022-01-20T09:07:35.190Z
}
----
conversation result { success: true }