What are Web Responders?

Web Responders (To Web) is an available responder application in all NetSapiens supported versions. It can be invoked for both incoming and outgoing calls.

The process generally looks like this: (1) create a dial translation in the Core server and then (2) use or host code that will respond and drive the call.

Web Responders represent the NetSapiens programmable voice functionality found in many other major CPaaS platforms, and function similarly. Building an interactive IVR or call-triggered API actions and more are possible with this feature, all based on your application's needs and how you develop it.

The most involved part of setting up Web Responders on the NetSapiens platform is the system configurations involved to manage call flow and handing off to the application, so please be sure to carefully review the following information about the system configurations. Additionally, it is advisable to perform an audit on your core and ensure things like your TTS license and configurations are set up properly, as responder application will rely on these services like any other would.

Things to Remember

Remember the following concepts when working with Web Responders:

• In Dial Translations, the Responder Application is called To-Web. The To-Web application first takes a single parameter: the URL of the WebResponder application. When the To-Web application is invoked, then IVR control is passed to the WebResponder application at the given URL.
• Whether the call is being forwarded on-net or off-net, you need to supply the "uid" which is the "owner" of the call. Optionally, you can also supply both "origination" and "destination", which are also passed through the dial plan.
• For all WebResponder verbs to work, we recommend using the logic "forward to user" rather than "forward to webresponder". The call flow should be routed through a user or system user. This is due to the way the Core Module works. The call needs an "owner" to execute certain operations, like "forwards" and such. Having the call going through a system user / subscriber ensures the subscriber has ownership of the call leg and can execute operations that require an owner. This setup is not exclusive to webresponder, every object is setup like that: call queues, conferences, etc...

Currently, the only way to create a system user that can function as a host for the dial translation for the purposes of passing call control to your Web Responder application with greater control and permanence is through the Admin Console. Here's an example of the configurations for a system user created for housing the resources and flow control for a WR app (please take note of the "service code" section at the bottom, "Generic System User" would be the preferred setting here):

System User Configuration Example

When certain systems like call queues are constructed in Portal, the users that correspond to their resource controls are system users and also created automatically through several background processes. When testing out a Web Responder flow, for the purposes of getting call control sent to your WR app through a temporary configuration, you can use a system user created by one of these processes, like one for a call queue for instance.

• You can direct inbound calls to a WebResponder application by routing to a system user and then forwarding to a dialplan entry that selects the "To Web" application. You can place an outbound call by dispatching an API call that will connect the remote end with that WebResponder, like so (the user in this example is "999@domain"):

object=call&action=call&callID=xxx&[email protected]&[email protected]&origination=6020001111

A couple important things to understand and remember from the perspective of the NetSapiens system configurations needed to make a Web Responder app function:

• DIDs need to be configured to point to a user in order to forward the calls to the correct dial translation,

DID Configuration Example

• The user answering rules, when creating a purpose-built system user for the express function of connecting call flow to a WR app, have to be set to forward to the dial rule created for passing the call control to Web Responder. To clarify, this is in reference to the "To Web" instructions, specifically the user answer rule settings as a "forward always", typically set in Portal as well.

• For the dial plan used to pass call control to Web Responder, here is an example of the settings you'd use when configuring in the Admin UI:

Dial Translation Configuration

Example Scenario

This is an example of a "math" application. The application prompts the caller for two numbers and says the sum. The application demonstrates (a) a multi-step application and (b) storing state in a server side php session. For this application to function, you must also create a file in http://localhost/tts.php and setup an account with a tts service.

URL Parameters Provided by NMS

When the Core Module posts back to the Web Responder application, the URL may contain the following parameters (regardless if it is inbound or outbound):

HTTP Tokens

Certain call flows may require an extended XML payload in the body, and in such cases an HTTP POST is industry standard for such actions. When configuring the Dial Translation in the Admin UI, you can use the Dial Translation Token "HttpMethod" to specify a POST verb in your call to your Web Responder application, like so:

<HttpMethod=POST>

More information on Dial Translation Tokens (including the other HTTP token "HttpSecret") can be found here: https://documentation.netsapiens.com/dial-translations/854615-what-are-the-available-dial-translation-tokens

More information in the form of an overview on Dial Translations themselves in the NetSapiens system can be found here: https://documentation.netsapiens.com/en_US/dial-translations/dial-translations-overview

Verbs

Verbs usually take an "action" attribute. If the "action" attribute is present, then control is returned to the URL given by the "action" attribute. If not present, then the application ends.

There are many actions that exist, but the following verbs are the only supported ones at this time.

Supported Verbs Prior to v44.1

Forward

The <Forward> action forwards to the given destination. The <Forward> verb does NOT take an "action" parameter. It is effectively a "goto".

<Forward>
  2125551212
</Forward>

Here are ByCaller instructions:

1. Add the "ByCaller" attribute to Forward.

   PHP

   root@[redacted]:/var/www/html# cat forward.php
   <Forward ByCaller='yes'>+141625[redacted]</Forward>

2. User sets forward to web responder.

3. The caller dials directly into the web responder. The forward will work as expected.

   CNmsUaSessionStateMsgInfoTest(20230130154940025425)('ByCaller','exist') - MsgInfo
   <ByCaller> exist
   LookupResponder(sip:ByCaller@Forward)
   - Found mode=(forward_call)
   LookupNextResponder case(1)
   Translate
   from
       <Forward@>
   by   (ByCaller)(Forward)
   to   (sip:ByCaller@Forward)(sip:ByCaller@Forward)

Gather

The <Gather> action gathers the given number of DTMF digits and posts back to the given action url, optionally playing the given .wav file.

In this example, it gathers 3 digits and posts back the relative URL "handle-account-number.php?Digits=555":

<Gather numDigits='3' action='handle-account-number.php'>
    <Play>
        http://www.example.com/what-is-your-account-number.wav
    </Play>
</Gather>

Play

The <Play> action plays the given .wav file and posts back (returns control) to the given action URL. (must be in WAV format).

In this example, it plays the WAV file and then posts back to continue.php. To end the call, omit the action parameter:

<Play action='continue.php'>
  http://www.example.com/hello-world.wav
</Play>

Supported Verbs in v44.1+

The following verbs have either been added or been given enhanced functionality starting in SNAPsolution v44.1. No functionality has been removed from verbs. This release is a feature enhancement, and your existing verbs will not break.

⚠️

Prerequisites

1. SNAPsolution v44.1
2. A Voice Services integration is required for these enhancements to work as expected. Deepgram is the recommended vendor in order to utilize all available voice attributes.

Response

The <Response> verb is designed to enhance the efficiency and structure of XML responses. By allowing multiple verbs to be encapsulated within a single <Response> element, this verb simplifies call control, eliminating the need for multiple requests to perform multiple sequential actions.

Previously, executing multiple verbs required individual requests. Now, with the introduction of the <Response> verb, developers can streamline call flows by listing multiple verbs under a single request. As the call progresses, the Core Module will sequentially move through the verbs listed within the <Response> element, executing each one in the order specified. Call control will move to the first action listed, or if it reaches the end, then it will disconnect the call since the <Response> is finished.

Here is an early exit example. The third <Say> won't execute because the call flow will be transferred to "next.php" specified by the action at the second <Say>.

<Response>
    <Say>This is Say XML tag 1 encapsulated in response tag</Say>
    <Say action='next.php'>This is Say XML tag 2 with action attribute encapsulated in response tag</Say>
    <Say>Call control has been transferred to "next.php" so this line will never execute</Say>
</Response>

Echo

The <Echo> verb allows for real-time audio feedback, enabling immediate playback of user input to facilitate testing. For instance, it might be used to immediately return received audio or input back to the sender. This could be used for testing or feedback purposes within a voice application. If a user says something, the system could use "Echo" to play back the user's words verbatim. If the timeout is not configured, then the "echo" will continue until the user hangs up.

<Echo timeout="5"></Echo>

Say

The <Say> verb instructs the system to convert text into speech during a phone call, so that the caller hears the text as spoken words. It uses TTS to convert text to audio sentences.

This verb relies on the API and the Voice Services integration to convert the sentence to audio for playback. Refer to the NetSapiens knowledge base article for enabling the configs for speech collection and configuring a vendor, "How Do I Configure and Use Text-To-Speech?" Note that Web Responders default to the value of these configs its system user is set to, and can inherit from domain or system level in case they are absent.

<Say>Hello, this is a simple text-to-speech message.</Say>

Gather (Enhanced)

The <Gather> verb already existed, but it can now also collect speech transcripts via voice (along with pressed digits).

On a technical level, this verb instructs the system to collect dtmf, speech, or both. If dtmf is specified and dtmf is collected, then a request will be sent