SIP Mediaserver Service - SIP Mediaserver Examples

This document provides practical examples of how to use the SIP Mediaserver Service from iotcomms.io to build advanced voice applications. The service enables fine-grained control over call handling and media interactions through REST APIs and real-time callbacks. This document combines key concepts, API functionalities, and practical use cases to demonstrate how developers can leverage the SIP Mediaserver Service in their applications.

The SIP Mediaserver Service provides a robust and scalable solution for managing real-time voice communications. It allows developers to handle incoming and outgoing calls, route participants, play media, capture input, and record conversations. Applications communicate with the SIP Mediaserver Service through REST APIs and callbacks to define call flows dynamically.

Core Concepts

The service operates using three main entities:

• Sessions – Represent a single call session, which may contain multiple connections and participants.
• Connections – Link two or more participants within a session.
• Participants – Individual entities engaged in the call, including SIP endpoints and IVR systems.

A session can be initiated in two ways:

1. A new call arrives at the SIP Mediaserver Service, creating an inbound participant.
2. An outbound call is placed using the /placeivrcall API, creating a participant that connects to a SIP destination.

The state logic determining how calls should be handled is implemented in the customer application. When state changes for sessions, connections, or participants, the customer application is informed about this by REST callback requests.

The key callbacks are:

• /newCall - sent to inform that a new call arrives to media service. The application should pass an action property in the response to tell how Mediaservice should handle the call:
  • drop - Disconnect the incoming call
  • call - Connect the call with another destination SIP participant
  • ivr - Connect the call with an IVR participant to play and receive media and tones
• /callNotify - these are informative events for progress updates for participants, for example, inform about ringing state
• /callEvent - these are events sent to inform that a connection or participant state has changed, and the application responds with an action to inform how to proceed. For example, if two participants are in a call with an associated connection, and one of the parties hangs up the call there is a /callEvent sent to inform about this. The action in the response then tells what to do with the remaining participant in the call.
  • drop - Disconnect the remaining participant
  • call - Connect the remaining participant with another destination SIP participant
  • ivr - Connect the remaining participant with an IVR participant to play and receive media and tones
• /callAnswered - This callback request is sent when a connection has been established between two participants in a session
• /sessionCompleted - This callback request is sent once all participants have left a session and therefore the session is deleted.

A special type of a participant in a session is the IVR participant. This participant act as an endpoint in a connection which can:

• Listen to DTMF tones sent by the other participant in the connection
• Play out phrases to be heard by the other participant in the connection, for example:
  • Phrases generated by text to speech
  • Play out files previously recorded or uploaded using the /promptfile API
  • Play out file fetched from a remote server from a provided HTTP URL
• Record audio sent by the other participant
• Set a background audio that should be played continuously while no other commands are executed, for example playing music on hold.´

Once a connection have been established with an IVR participant it will trigger a /getIvrCommand callback request. The response to this request should have an command that provide instructions to the IVR participant.

The body of the /getIvrCommand request may contain information from a previous command execution, for example collected DTMF digits.

The body of the /getIvrCommand response contain the command to be executed, for example to play out a phrase. Once a command have been executed a new /getIvrCommand request is sent until the response contain a hangup:true property. This will hang up the IVR participant from the connection and trigger a /callEvent callback to get information what to do with the party previously connected with the IVR participant.

/getIvrCommand response object

Details of /getIvrCommand callback requests and responses can be found in the Mediaservice API documentation.

The response to the callback object contain a command that provides instructions to the IVR participant. It is a JSON object of the format:

{
  "dtmf": {},
  "phrases": [],
  "backgroundPrompt": {},
  "hangup": false,
  "getIVRCommandAfter": 20,
}

Where:

• dtmf property is an object telling the IVR participant to listen for and report DTMF digits received. Received digits are reported in subsequent /getIvrCommand requests
• phrases is an array of phrase objects. A phrase object instructs the IVR participant to play out audio to the connected participant. Once all phrases have been played a new /getIvrCommand callback request is sent to get further commands.
• backgroundPrompt is an object with information telling the IVR participant to loop audio in between command execution.
• hangup is a boolean property telling the IVR participant to drop out from the connection, i.e. when either connect the connected participant with another party or to end the session. When this property is set the command provided will be executed but no further /getIvrCommand callbacks will be sent. Instead a /callEvent callback request will be sent indicating that the IVR participant have left the connection.
• getIVRCommandAfter is a property telling the IVR participant to pause the next /getIvrCommand request the time specified in seconds.

The list above is an overview of the most commonly used properties, for more detailed information, please look at the API documentation.

This example demonstrates how to implement an IVR-based call routing system that greets the caller, captures input, and routes them to the correct department.

Below is an example of a typical message flow where the Mediaservice interacts with a customer's application implementing an auto-attendant function.

1. A call arrives to the phone number provisioned for the Mediaservice. This trigger a /newCall callback request
2. The application respond with a 200 Ok to the callback having a body telling the service to connect the caller with an IVR participant.
3. The SIP call is established and a /callAnswered callback request is sent to indicate that a connection have been established between caller and IVR participant.
4. Media path is established between caller and Mediaservice
5. A /getIvrCommand callback request is sent to the application to get instructions.
6. Application responds back with a command to listen for a single DTMF tone and play a greeting phrase using Amazon Polly text to speech. IVR participant will wait until the DTMF matches one digit.
7. Caller press digit 2. This trigger a new /getIvrCommand which contain the matched digit.
8. Application responds with a connection phrase and set hangup:true property to hang up the IVR participant.
9. This triggers a /callEvent callback indicating that IVR participant have been disconnected.
10. Application responds with a action:"call" and a destination to connect the caller with.
11. Mediaservice creates a new participant representing the callee and establish a SIP call with the provided destination.
12. Callee answers the call which creates a new connection in the session for caller and callee. This triggers a /callAnswered callback.
13. Caller decides to hang up the call. This triggers a /callEvent to the application.
14. Application responds with a action:drop to hang up the remaining participant representing the callee. This will trigger a SIP Bye to be sent for that call leg.
15. No more participants exists for the session which triggers a /sessionCompleted callback to be sent to the application.

Below is a simplified sequence diagram where some callbacks such as /callNotify have been omitted. A detailed description of callbacks and API can be found in the Mediaservice API documentation.

1. When iotcomms.io Mediaservice receives an incoming call to a destination to be recorded, a /newCall callback request to the application. This will send a response telling the service to connect the call with the callee and enable recording. Recording is enabled by setting the callRecording:true property in the /newCall callback response. A filename is also provided in the response.
2. Mediaservice places an outbound call to the callee.
3. Call is connected, and parties talk to each other.
4. Call is disconnected.
5. Mediaservice sends a /recordingReady callback to indicate that the recording is ready for download.
6. Recording is downloaded using the /promptfile API

Below is a simplified sequence diagram where some callbacks such as /callNotify have been omitted. A detailed description of callbacks and API can be found in the Mediaservice API documentation.

Call monitoring allows a third party to listen to an ongoing call without participating in the conversation. This is enabled by providing a monitorDestAddr property in the /newCall response. The SIP Mediaserver Service will establish a new SIP call to this address after the initial /callAnswered event is sent. The monitor user will receive an audio stream that contains a mix of the audio from all active participants in the call.

Message Flow

1. A call arrives at the Mediaservice, triggering a /newCall callback.
2. The application responds with an action to connect the caller with a callee and includes monitorDestAddr to enable call monitoring.
3. Mediaservice places an outbound call to the callee.
4. Once the callee answers, a /callAnswered callback is sent to the application.
5. Mediaservice then initiates a SIP call to the monitor user.
6. The monitor user answers the call and begins receiving the mixed audio stream.
7. When the caller or callee disconnects, a /callEvent callback is sent, and the application decides how to proceed.
8. If all participants disconnect, a /sessionCompleted callback is sent.

If you wish to make outbound calls when there are no inbound call that initiated the process it is possible to use the /placeivrcall API. It will create a participant in the same way as a call participant was created when a call comes in and the application is notified using the /newCall callback.

Here is an example on how to use the /placeivrcall API:

The sequence is initiated with a placeivrcall.

While the call is progressing a number of callbacks will be generated towards the application. Most of them are just status information indicating the progress of the call. The only callbacks that really need handling is the getIvrCommand which needs to be responded with a parameter action with value call and then a destination address parameter with the phone number of the ARC and then at the end of the call there will be a callEvent callback indicating that either party of the call has hung up. A proper response is then to send a property action with value that specify to drop either the calling party or called party.

Message flow

1. A /placeivrcall is initiated from the application with the destination address set to the phone number of the device to call.
2. As the call progress towards the device there will be a /callNotify callback telling that it is ringing in the device.
3. When the device answer there will be a /callAnswered callback telling that the user has answered.
4. The system now need to know how to process the call and sends a /getIvrCommand callback. This callback can be responded with a "action": "call" which then connects the device to another device as specified in the response to the getIvrCommand.
5. The call is now connected to the other device and the progress is reported in /callNotify callbacks.
6. Eventually the call is answered by the other device and the two devices are now able to talk to each other.
7. One of the devices hang up and there will be a /callEvent callback to ask what to do with call now. In this case the application decides do drop the call.
8. Finally there will be a /sessionCompleted callback telling that the session has ended and the call has completed.

Attended call transfer allows a participant to be placed on hold while another call is established, and then either completed (transfer) or canceled (return to original call). This is implemented using the concept of splitting an ongoing connection, invoke IVR parking, and re-connect with another party.

The SIP Mediaserver Service enables full control of attended transfer flows by letting the application manage each participant independently through /callEvent callback responses.

Key concepts

• Attended transfer is built using:

  • /splitconnection to trigger /callEvent callbacks for participants active in a connection
  • /callEvent action:"ivr" to connect the party put on hold with hold music
  • /callEvent action:"call" to connect create the inquiry call
  • /connect to connect two participants to complete the call transfer

Message flow – Attended transfer

The example below shows a standard attended transfer where User A calls User B, B initiates a transfer to User C, and then completes the transfer so A and C are connected. When parties are connected and transferred the SIP re-invite sequences are left out for readability.

The SIP Mediaserver Service supports dynamic audio conferencing by allowing an application to merge multiple participants into a shared media connection. A conference is created by combining existing call legs into a conference connection using /createconferenceconnection, /splitconnection, and /callEvent callback responses.

Conference handling builds on the same primitives as attended transfer:

• Splitting existing connections to isolate participants
• Using IVR to park participants (hold music or announcements)
• Creating new call legs
• Joining participants into a shared conference connection

This allows the application to fully control how and when participants are added to the conference.

Key concepts

• Conference is built using the same primitives as attended transfer:

  • /splitconnection to isolate participants and trigger /callEvent
  • /callEvent action:"ivr" to park participants during setup
  • /callEvent action:"call" to establish new call legs
  • /createconferenceconnection to create the shared media connection
  • /callEvent action:"joinconferenceconnection" to add participants to the conference

• Important identifiers to track:

  • connectionId and replyId for all connections (used in /splitconnection and for joinconferenceconnection)
  • participantId for participants that will later be joined into the conference

• IVR is used to:

  • park participants (hold)
  • provide hold music or announcements

• Once joined, all participants receive a mixed audio stream from the conference connection

Message flow – Conference with park and retrieve

The example below shows how a conference between User A, B, and C is established. User A is first connected with B. A then puts B on hold and calls C. Once A is connected with C, a conference connection is created and A, B and C are joined into the same conference. When parties are connected the SIP re-invite sequences are left out for readability.