Here are ByCaller instructions:

1. Add the "ByCaller" attribute to Forward.

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

1. User sets forward to web responder.
2. 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)

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>

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 

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 bamustck 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 repeat the user's words. If the timeout is not configured, then the "echo" will continue until the user hangs up.

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

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.

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

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 with the “Digits” param back. If speech is specified, then it is collected through speech_cmd and a request is sent back with the transcript in “SpeechResult”.

 <Gather input='dtmf speech' action='process_action.php’>  
   <Say language=‘en-US’ voice=‘amy’>  
     Hi, how can I help you today ?  
   </Say>  
 </Gather>

<Gather> can contain nested verbs like <Say> or <Play> that can execute while the system is gathering speech or DTMF.

It relies on the API and the Voice Services integration to convert the sentence to audio for playback. We recommend that you use Deepgram as your default vendor to utilize all of the available voice attributes. 

 <Response>  
     <Hangup/>  
 </Response>

The <Stream> verb bidirectionally streams media in & out via a WebSocket server in near real-time. Developers can both intercept and inject live audio, making it invaluable for applications requiring real-time audio processing, such as AI-driven analysis and interactive voice response systems.

The application can send a stop event to close the stream through the WebSocket. Upon receiving a "stop" event, the <Stream> will stop transmitting. If it is a Sync stream, then it will exit and proceed to the next Web Responder action.

{
    "event": "stop"
}

📘

There are two ways to start a Stream: asynchronous (listen only) & synchronous bi-directional (transmit & listen).

When used within a "Start" verb, "Stream" enables asynchronous audio streaming. It's NOT bidirectional; it's only in one direction. This allows the call to proceed while audio is being transmitted. Asynchronous audio is streamed to the WebSocket URL.

In the following example, audio is streamed to wss://example.com/audio while the call continues with the next instruction, preventing call interruption. If no further instructions are provided, the call may be disconnected; therefore, it is advisable to include subsequent Web differentResponder instructions to continue the call session.

<Response>
    <Start>
        <Stream name="my_stream" url="wss://example.com/audio" />
    </Start>
    <Say>This will execute after connecting the stream</Say>
</Response>

If a unique name was used to start the asynchronous stream, then the stream can be stopped at any time by providing its name within a "Stop" verb, like so:

<Response>
    <Stop>
        <Stream name="my_stream"/>
    </Stop>
</Response>

For applications requiring synchronous bi-directional streaming where you might need to send audio back to the call or interact with the caller based on the streamed audio, you should use the "Stream" verb within the "Connect" verb. This facilitates a two-way audio stream between the call and your application, enabling interactive scenarios.

<Connect>
    <Stream url="wss://example.com/audio"></Stream>
</Connect>

Custom parameters can be added to the "Stream" verb to pass additional information to the WebSocket server. These parameters are sent with the "start" WebSocket event and can be used to provide context or session-specific data.

In this example, customerID and callType are passed along with the audio stream, allowing the server to tailor the processing based on these parameters. These parameters allow for the transmission of contextual information or session-specific data to the receiving application, enhancing the call's processing and analysis.`

<Stream name="word_detection" url="wss://example.com/audio" track="both">
    <Parameter name="customerID" value="12345" />
    <Parameter name="callType" value="support" />
</Stream>`

📘

Life Cycle of a <Stream> Verb

In the life cycle of a "Stream", several types of events are The parameter's name acts as the key in the key-value pair sent to the endpoint.represented through WebSocket messages: Connected, Start, Media, and Stop. Each message sent over the WebSocket is a JSON string. The event property within each JSON object identifies the type of event occurring.

The Connected message is the first to be sent once a WebSocket connection has been established. Its attributes are:

• event: a string value "connected" indicating the establishment of the connection
• version: indicates the semantic version of the protocol

 {  
     "event": "connected",  
     "version": "1.0.0"  
 }

Sent immediately after the Connected message, the Start message contains essential information about the Stream and is dispatched only once. Its attributes are:

• event: a string value "start"
• sequenceNumber: tracks the order of message delivery, starting with "1"
• start: an object containing Stream metadata such as stream_id, call_id, expected tracks, customParameters, and mediaFormat.

 {  
     "event": "start",  
     "sequenceNumber": "1",  
     "start": {  
         "stream_id": "2d9be7d7-4a66-4667-b2e1-cf3fa4e66306",  
         "call_id": "vmj74pd5nmm9jlukvbfg",  
         "tracks": [  
             "inbound",  
             "outbound"  
         ],  
         "customParameters": {  
             "client_id": "123123123",  
             "status": "1"  
         },  
         "mediaFormat": {  
             "encoding": "audio/x-mulaw",  
             "sampleRate": 8000,  
             "channels": 1  
         }  
     }  
 }

A Media message encapsulates the raw audio data within the stream. Its attributes are:

event: a string value "media"

sequenceNumber: increments with each new message

media: contains the audio payload and additional metadata like track, chunk and timestamp

chunk: this attribute signifies the sequence of the audio packets being sent on that track. The first message will start with chunk "1" and increment with each subsequent message. This sequential numbering helps ensure that audio frames are processed in the correct order, maintaining the integrity of the conversation.

timestamp: this represents the presentation timestamp of each audio chunk relative to the start of the stream, in milliseconds.

 {  
     "event": "media",  
     "sequenceNumber": "3",  
     "media": {  
         "track": "outbound",  
         "chunk": "1",  
         "payload": "base64AudioData",  
         "timestamp": "1708388604"  
     }  
 }

A Stop message indicates the Stream's termination or the call's end. Its attributes are:

event: a string value "stop"

sequenceNumber: increments with each new message

stop: contains metadata about the Stream session

bytesSent: this indicates the total amount of data transmitted during the stream for each enabled track.
duration: This reflects the total duration of the audio stream for each track, typically measured in seconds.

 {  
     "event": "stop",  
     "sequenceNumber": "416",  
     "stop": {  
         "tracks": [  
             {  
                 "type": "inbound",  
                 "bytesSent": 66240,  
                 "duration": 8  
             },  
             {  
                 "type": "outbound",  
                 "bytesSent": 99114,  
                 "duration": 10  
             }  
         ],  
         "call_id": "24j83iflgottdokd39vt",  
         "stream_id": "6ccf2088-6755-4861-a162-3c6c30d6ad07"  
     }  
 }

The <Wait> verb can be used to include configurable pauses within a call flow. It instructs the system to pause for a specified duration before proceeding with the next instruction in the sequence. This can be particularly useful for creating delays within voice interactions, such as spacing out verbal prompts to make them easier for the user to understand. If a wait timeout is not configured, then the system will default to waiting 1 second.

<Wait timeout="5"></Wait>

Starting in v44, Web Responders will now show as a call participant in the call trace.

Here is an example testing scenario:

1. Contact Support to create a dial translation for the Web Responder using the application "To Web".
2. Use the "destination" of the above dial translation and set it as a user's forwarding rule.
3. Call the user. The following trace should show the Web Responder as the call participant ("POST").

Web Responder Enhanced Security