SIP Interconnect and Pinless PSTN Dialin

Pinless PSTN Dialin and SIP Interconnect

Quick Overview

Daily's default behaviour for sip and PSTN dialin is to forward the call directly to a specified Daily Room. This means that the calling user MUST know the destination sip_uri or phone number and pin combination. There are use cases such as contact centers where the destination is not known ahead of time, Daily now exposes a Static SIP URI or the Pinless phone number.

When a call arrives at the pre-defined Static SIP URI or Pinless phone number, the following steps need to be undertaken:

Daily will trigger a webhook to your infrastructure. The webhook location is defined in the room_creation_api of pinless_dialin REST API.
When the webhook triggers on your infrastructure, you can decide on how to route the call, for example, create a new Daily Room or route it to an existing Daily Room.
While your infrastructure is creating or picking out the correct room to route to, the incoming call on Daily is placed on hold, i.e., the incoming caller is listening to hold music.
Once you have chosen or created a Daily Room, you have to wait for dialin-ready to fire. Once the dialin-ready fires, you can update the held incoming call with the sipUri by calling pinlessCallUpdate.

Provisioning SIP Interconnect and Pinless Dialin Workflow

To create the pinless or sip interconnect workflow you will need to call the pinless_dialin REST API. The REST API takes as input a Daily purchased phone number and the webhook url to trigger when an incoming call is received on the purchased phone number. Alternatively, for sip-interconnect, since there is no need for a phone number on Daily, you can skip the field.

A unified example of setting up both the pinless PSTN and SIP interconnect is as follows. In this case, we are providing two different webhooks for the phone number and SIP interconnect.

The response is the create room's config object containing an array of pinless_dialin. Each object contains a static sip_uri and the corresponding room_creation_api webhook url.

When configuring the pinless_dialin, Daily will send a request to the room_creation_api endpoint with a test request body. It can be used to verify the endpoint. Even if we do not receive 200 response, endpoint is configured to maintain backward compatibility for existing domains which may not recognize the test body.

test body sent for verification -

The pinless_dialin configuration will return hmac secret that you can use to verify the signature of a daily call. You may also pass in an hmac in the pinless_dialin request body, if you'd like to specify your own secret. This secret must be BASE-64 encoded.

Note that if hmac is not passed, Daily will generate new hmac on every call to set pinless_dialin.

Incoming call triggers the webhook

When a call is received at one of the $PURCHASED_NUMBER or the sip_uri, Daily sends the following JSON to the configured webhook ( https://webhook.example.com/handle_twilio_daily_room). In order to signify to the caller that the call has been received and is being processed (by your webhook), Daily places the incoming call on hold and the caller hears hold music.

The webhook that is received by your infrastructure contains To: and From: fields that can help you decide between creating a new room or routing to an existing room.

The From represents the sipuri or the phone number of the caller, while the To represents the Daily static sip address or the purchased number. The callId and callDomain fields are read-only, they are used to connect the incoming call that is on hold to the chosen Daily Room.

`hmac`

The hmac field contains a secret that is shared between Daily and you. Ensure that you do not share this secret publicly, otherwise you will not be able to verify that an event came from Daily.

pinless_dialin response contains hmac, which is a BASE-64 encoded HMAC-sha256 secret that allows you to verify that the room_creation_api call is actually came from Daily. You may also provide your own secret when creating a webhook, as long as it is BASE-64 encoded. When POSTing to your webhook server, Daily will provide two headers: X-Pinless-Signature and X-Pinless-Timestamp.

In order to verify the signature yourself, you'll need to compute the signature in a manner provided in the snippet below:

body is the body POSTed to room_creation_api. From there, you can sign the content with the HMAC-sha256 string, and ensure that your signature matches the one in the X-Pinless-Signature header. As only Daily and you hold the hmac, this comparison ensures that the request came from Daily.

Connecting the Incoming call to the Daily Room

Once your infrastructure has created a new Daily Room, a pipecat bot or a user needs to join the Daily Room so that the incoming call can be forwarded to this room. In addition to joining the call, dialin_ready needs to fire. At this point the Daily Room is ready to receive the incoming call.

Call pinless_dialin REST API with the Daily Room's sip_uri and the callId and callDomain from the JSON in the webhook. These fields as a whole helps Daily idenfy the incoming call session and patch it to the sip address assocaited to the Daily Room.

Connecting the incoming call to the Daily Room before `dialin-ready` may result in the call dropping.

Depending on your Daily room configuration, you may have one or more sip_uri's provisioned, make sure that the sip_uri that you will provide to pinlessCallUpdate is currently not being used by another SIP Client.

To learn more about how Pinless PSTN dialin or SIP Interconnect with Twilio is used in Voice bots, read our pipecat dialin docs.