Course11:Advanced - WEBMEDIA

From innovaphone wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
There are also other versions of this article available: Course11 (this version) | Course10 | Course12

A book about innovaphones RTP to HTTP interface.

WEBMEDIA

WEBMEDIA in innovaphone speech is a media data that is not sent or received by an IP phone or ISDN gateway, but rather by an HTTP stream.

The WEBMEDIA is used in innovaphone PBX by the following applications:
  • Music on Hold
  • Waiting Queue
  • Voice Mail

The HTTP Interface

If you take a look at the Web UI of innovaphone products, you will never find the word WEBMEDIA on the configuration pages. In effect, the virtual term WEBMEDIA refers to an absolutely tangible interface that can be found on any innovaphone IP adapter or gateway - an HTTP interface.

The HTTP interface can read encapsulated RTP data from a file via HTTP and send the RTP packets to a VoIP endpoint. In other words the HTTP interface is a gateway between HTTP and VoIP. Similar to an ISDN Gateway connecting ISDN and VoIP - an HTTP interface can convert data between HTTP and RTP. There is no codec conversion performed by the HTTP interface. If a G.711A codec is negotiated on the incoming call to the HTTP interface, it must read data from the file with G.711A RTP data.

You're probably wondering how the HTTP interface knows which file and from which location it has to be delivered. The answer is that the URL to the file is provided in the call signaling by the User to User Information.

This following picture reveals exactly what happens when an IP phone calls a Waiting Queue having an announcement myMusic.g711a configured. The steps are:
  1. The number of WQ is dialed on the phone ad the call is sent to the PBX.
  2. The PBX delivers the call from User Object to the Waiting Queue Object.
  3. The Waiting Queue adds the announcement URL http://1.2.3.4/myMusic.g711a to the User-Data filed in the call signaling and places the call to the registration Object of the HTTP interface.
  4. The PBX sends the call to the HTTP interface.
  5. The HTTP interface extracts the URL from User-Data field and makes a HTTP GET request according to the information provided in the URL.
  6. The HTTP server starts to deliver the file myMusic.g711a to the HTTP interface.
  7. The HTTP interface encapsulates the data from file into RTP packets and sends it to the endpoint.




In fact, normally you don't have to register the HTTP interface in the PBX if you configure a Waiting Queue. The PBX uses implicitly always the local HTTP interface. However it is possible and sometimes even necessary to use a non-local HTTP interface. In the next chapter we will see why and how it should be done.

Offloading of the HTTP interface

By offloading the local HTTP interface of the PBX, the own interface is not used, but the HTTP interface of another gateway is used instead for playing MoH, WQ announcements etc. The offloading of the HTTP interface should be done primarily for performance reasons. This can be necessary in scenarios with a large number of endpoints that could be connected to the MoH or a Waiting Queue at the same time. For example an IP2000 can handle up to 250 concurrent users connected to a Waiting Queue and listening to the same announcement. Also playing a dial-tone via G711 RTP for 1000 users (e.g. in a provider scenario) could produce too much workload for the PBX hardware.

When is it necessary to offload?


The simplest check you can do is to take a look on the CPU-R counter of the gateway running the PBX. It can be found under fish-help.png Administration/Diagnostics/Counters in the web interface. The CPU-R counter shows how many CPU cycles are reserved on the PBX for call processing.

Configuration


The offloading is configured by additional parameters that can be found on every configuration page where an URL for an HTTP interface is provided. If you take a look on the configuration page of a Waiting Queue object, you will find the field for "Extern Name/No" under the URL input box. At this point you can provide a number(it could be external number too) or a name of the PBX object that could be called, instead of placing a call to the local HTTP interface. So it is possible to create a PBX Object(e.g. Gateway) and to register a HTTP interface from an external gateway on it. After that, the name of this object can be used under "Extern Name/No". You can even register HTTP interfaces of multiple devices on the Gateway object for load balancing. The Gateway object will distribute the calls in round robin fashion.


When providing the URL for the HTTP interface the loopback IP address 127.0.0.1 should be used, in order the HTTP server is offloaded to the local compact flash card of each gateway and load balancing on of HTTP serves is implemented too. Otherwise, if an IP address of the HTTP server is provided, all HTTP interfaces will fetch data from this single HTTP server.

Another way to provide different URL is to insert it in the UUI field of the routing table.

Since different gateway types can handle different amount of calls to the HTTP interface and different gateway types could be used for offloading at the same time, it is necessary to limit the number of calls to a smaller gateway by using counters in the routing on a particular device.

In this way the hardware restrictions of a single gateway are no obstacle for building a system with a big number of WEBMEDIA channels.

URL Parameter for HTTP Interface

It is possible to provide some additional parameters to the HTTP interface by using URL query strings.

Codec Selection


The most widely used parameter is coders. Since the HTTP interface cannot convert codecs, every announcement must be provided in all codecs that could be used by endpoints after codec negotiation. For this you will place files on the HTTP server which contains the announcement in various codec formats, e.g. announcement.g711a, announcement.g711u, announcement.g729, announcement.g723. To provide a single URL which matches to all files the parameter coders is used.

The syntax of coders parameter is as follows:
filename.$coder?coder=g711a,g711u,g729,g723

This means, $coder will be replaced by one of the codecs provided in coder=. The selected coder always corresponds to the negotiated coder. In case that the calling endpoint uses g729, following filename will be used:
filename.g729

In case that no appropriate codec is available as a file for the HTTP interface, the call will be terminated with a cause "No channel available". This will happen, for example if following URL is configured
http://1.2.3.4/filename.$coder?coder=g711a,g711u
and the calling endpoint supports only G729 codec.

Currently available codecs are:
  • g711u
  • g711a
  • g729
  • g723
The best practice to configure an URL for HTTP interface is to copy the URL of one of the media files from Diagnostics/CF/Browse CF Content(HTML) by using the "Copy link address" option of the browser. Than to paste it to the URL config and to replace the filename extension by the string:
$coder?coder=g711a,g711u,g729,g723

Playback Options


Additionally to the coders selection parameters further options are available. This options can be appended to the existing parameters by using ampersand & .

The option repeat=[true|n] can be used to force the HTTP interface to start to play the file again from the beginning, if the end of the file is reached. It should be used if a custom MoH is configured on the PBX/General Configuration. The URL with this option appended could be:
http://1.2.3.4/filename.$coder?coder=g711a,g711u,g729,g723&repeat=true

In case the file should be played not from the beginning, but from a random position the parameter random=true can be used. For example if a customer requirement is to play various pieces of music in MoH, a single big file with all compositions can be created and used with the random=true parameter.

Recording Option


The HTTP interface can also write files to WebDAV servers. The direction of media data is reversed. This is used mainly in the VoiceMail implementation. The option can be enabled by using the URL parameter record=true.

In recording mode it is possible to define which codec should be used (in other words which codec should be negotiated by the HTTP interface). E.g. if following URL parameter is used $coder?coder=g711u the HTTP interface will negotiate a call with G711u and will create a file filename.g711u.

MoH and TONE


There are pseudo URLs available, that can be used instead of complete URLs. MoH will play the built-in music on hold.

It is also possible to generate tones by the HTTP interface instead of playing music files. This can be done with pseudo URL TONE. Playing tones can be useful if you want to lead the caller to believe that there a dialing, busy or ringback tone. The parameter tone can be used with the following values:
  • ringback - ringback tone is played (alerting on the called site)
  • busy - busy tone is played
  • dialing - plays dialtone (this option is default if only TONE without parameters is used)
The usage is:
TONE?tone=busy

DTMF


The URL parameter digits can be used if a DTMF sequence must be sent to the caller before a file is played. This parameter can be added to any URL(real or pseudo), and the DTMF sequence is played before the file starts to play.

Usage:
digits=p0123456789*#

Note: if you wish to send DTMF # then we must repeat 2 times, ie: digits=## to send only one "#".

Combine DTMFs and Tones


It is possible to combine DTMF Tones and Busy/Ringback/Dialing Tones in one URL.

E.g. it is required on an incoming call to send DTMF digits *123 followed by a Busy Tone. The URL for this will look like:
TONE?digits=pp*123pp&tone=busy&repeat=true

Troubleshooting


In case you have troubles configuring the URL for the HTTP interface, you can add a trace parameter to the URL, in order to activate the extended tracing output of the HTTP interface.

Usage:
trace=true

FQDNs


You can use fully qualified domain names in the host part of an URL in V10, instead of an IP address. This is actually a feature of he built-in HTTP client, so this is true for all places where an URL can be configured.

However, this of course requires a working DNS configuration, which opens room for failure. You should thus use FQDNs with care only.