XML API for SIP Phones 31xx

XML API Guide (en) Version 2.6

tiptel 31xx

tiptel

XML API for Tiptel.com SIP Phones 31xx

Last changes: 09.12.2014

Table of contents 1 Abbreviations..........................................................................................................................................................2 2 XML Services.........................................................................................................................................................3

2.1 Phone initiated service....................................................................................................................................3 2.1.1 Action URL - PBX Sync.........................................................................................................................3 2.1.2 Programmable function key....................................................................................................................3 2.1.3 External XML phone book service.........................................................................................................3

2.2 External initiated service.................................................................................................................................4 2.2.1 HTTP Remote Action-URL....................................................................................................................4 2.2.2 SIP NOTIFY Remote Action-URL.........................................................................................................4 2.2.3 HTTP Push XML....................................................................................................................................5 2.2.4 SIP NOTIFY Push XML.........................................................................................................................5

2.3 XML Format...................................................................................................................................................6 2.4 External URI formats......................................................................................................................................6

2.4.1 URL variables.........................................................................................................................................7 2.5 Internal call control URI formats....................................................................................................................8

2.5.1 Internal URI Dial:...................................................................................................................................8 2.5.2 Internal URI SendDigits:........................................................................................................................8

2.6 Internal device control URI formats................................................................................................................8 2.6.1 Internal URI "Key:"................................................................................................................................9 2.6.2 Internal URI "Led:"...............................................................................................................................10 2.6.3 Internal URI "Command:"....................................................................................................................11 2.6.4 Internal URI "SoftKey:"........................................................................................................................11

3 XML objects.........................................................................................................................................................13 3.1 IPPhoneExecute XML object........................................................................................................................13 3.2 IPPhoneConfiguration XML object..............................................................................................................14 3.3 IPPhoneTextMenu XML object....................................................................................................................14 3.4 IPPhoneTextScreen XML object...................................................................................................................18 3.5 IPPhoneInputScreen XML object.................................................................................................................20 3.6 IPPhoneDirectory XML object (Type A)......................................................................................................25 3.7 IPPhoneStatus XML object...........................................................................................................................28 3.8 IPPhoneDirectory XML object (Type B)......................................................................................................30 3.9 IPPhoneText XML object.............................................................................................................................32 3.10 IPPhoneMenu XML object.........................................................................................................................34 3.11 External XML phone book..........................................................................................................................35 3.12 XML Device Info........................................................................................................................................36 3.13 Sub objects for UI XML objects.................................................................................................................37

3.13.1 Sub object "SoftKey" for XML UI objects..........................................................................................37 3.13.2 Using the internal object "SoftKey” for customizing hard keys..........................................................38 3.13.3 Sub object "SoftKeyItem" for XML UI objects (Type B)...................................................................39

3.14 Special attributes for UI XML objects........................................................................................................40 3.14.1 Timeout...............................................................................................................................................40 3.14.2 LockIn.................................................................................................................................................41 3.14.3 triggerDestroyOnExit/ destroyOnExit.................................................................................................41

4 HTTP API.............................................................................................................................................................42 4.1 HTTP GET Device control URLs.................................................................................................................42 4.2 HTTP GET Service URLs.............................................................................................................................42

5 HOW TO..............................................................................................................................................................43 5.1 HOW TO push XML file via HTTP..............................................................................................................43 5.2 HOW TO push XML file on Asterisk via SIP NOTIFY................................................................................43 5.3 HOW TO trigger remote action URL via HTTP...........................................................................................44

Page 1 / 50


5.4 HOW TO trigger remote action URL on Asterisk via SIP NOTIFY.............................................................44 6 XML Schema, XSL Model...................................................................................................................................45 7 History..................................................................................................................................................................46

List of tablesTable 1: Customizable hard keys in object “SoftKey”..............................................................................................39Table 2: Customizable hard keys in object “SoftKeyItem”.......................................................................................40

1 Abbreviations

API Application Programming InterfaceSIP Session Initiation Protocol UI User InterfaceURL Uniform Resource Locator, in this document the same as URI URI Uniform Resource Identifier RFCs 1630, 3986XML eXtensible Markup Language

Page 2 / 50


2 XML ServicesThe phone provides two methods to run the XML service,

– initiated by phone device– initiated by external server

There are basically 3 types of XML objects:1) User Interface objects are XML objects which will use the display of the phone to show the content of

XML file.2) Device control objects are XML objects used to execute commands or configure the phone. There are no

interaction witch user.3) XML phone book for build-in Merge-Service

2.1 Phone initiated serviceThe phone use TFTP, FTP or HTTP(S) GET command to download the XML file from the external server. Each time the phone try to interpret downloaded data. If there defined XML objects are detected the content will be accordingly processed.

2.1.1 Action URL - PBX Sync

On predefined internal phone and call events the corresponding configured Action-URLs will be triggered automatically by device. See chapter PBX Sync in Administrator Guide / Wiki to configure this kind of URLs for corresponding events.

2.1.2 Programmable function key

Any Action-URL can be triggered manually by hitting a function key configured accordingly on the phone or extension module. See chapter DSS Key and EXT Key in Administrator Guide / Wiki to configure this kind of URLs for corresponding keys.

2.1.3 External XML phone book service

Since firmware version 2.x there are different ways to entry the default phone book.

Option 1)There are a build-in service to merge an external XML phone book in to internal phone book. The URL of XML file and pooling interval must be configured to use this service. The XML-File should contain IPPhoneDirectory object type A or B.

Option 2)An external LDAP-Server can be used.

Option 3)An external WEB-Service can be used to get filtered contacts. Therefore a Service-URL using {filter} runtime variable must be defined. The phone device collects the user input, replaces the variable by characters and performs http GET. The Web-Service should evaluate the search request and must deliver the IPPhoneDirectory-Object witch

Page 3 / 50


requested contacts.

Option 4)A simply Action-URL can be defined as entry point for a phone book in context of XML-Minibrowser. On the phone with the alpha keyboard the URL-Variable {search_key} will help to send a initial search filter character to the server. IPPhoneMenu-Object can be used to show entries. The Softkey-URLs for keys “1” till “9” should be defined to collect the pressed keys by Web-Service and perform the look up queries on basis of T9-Model.

2.2 External initiated serviceIn the context of remote access there are different ways to initiate the downloading of XML file or send the XML data directly to the phone.

2.2.1 HTTP Remote Action-URL

The downloading of XML file can be triggered by using HTTP GET method calling remote URL on device build-in Web Server.

http://phoneip/cgi-bin/remote/devctl?minibrowserurl=url

The query string must contain the URL of XML fileminibrowserurl=url

The phone returns 200 OK and downloads the XML file.

Example:

This example will induce the phone with IP 192.168.1.103 to download the XML file from http://myserver/mymenu_192.168.1.103.xmlPlease consider that URL-Variable {ip} should be escaped in form of %7Bip%7D to be RFC conform.

2.2.2 SIP NOTIFY Remote Action-URL

The downloading of XML file can be triggered by using proprietary SIP NOTIFY event "tiptel-actionurl"

Example:

Page 4 / 50

http://192.168.1.103/cgi-bin/remote/devctl?minibrowserurl=http://myserver/mymenu_%7Bip%7D.xml


This example will trigger the phone with IP-Addr. 192.168.1.103 and MAC-Addr. 000CC4300086 download the XML file from http://192.168.1.1/myfiles/mymenu_000CC4300086.xml

2.2.3 HTTP Push XML

XML data can be send to the phone using HTTP POST method. The Content-Type Header must be set to "text/xml". Require user 'admin'

Example:

This example will turn the display back light on, See IPPhoneExecute object and URI Led for more details.

2.2.4 SIP NOTIFY Push XML

XML data can be send directly to the phone using proprietary SIP NOTIFY event "tiptel-xml" with XML content.

Example:

Page 5 / 50

POST /xmlservice HTTP/1.0 User-Agent: Wget/1.11.4 Accept: */* Host: 192.168.1.20 Connection: Keep-Alive Content-Type: text/xml Content-Length: 140

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneExecute Beep="yes"> <ExecuteItem URI="Led:BACKLIGHT=on"/> </TiptelIPPhoneExecute>

NOTIFY sip:[email protected]:5060 SIP/2.0Via: SIP/2.0/UDP 192.168.1.101:5060;branch=ad5jh4ut9dsnf3jtf;rportFrom: <sip:[email protected]:5060>;tag=54dg7853c4To: 3030 <sip:[email protected]:5060>Contact: <sip:[email protected]>Call-ID: 65835h8s46f2x429CSeq: 20 NOTIFYMax-Forwards: 1Event: tiptel-actionurlContent-Type: text/plainContent-Length: 37

http://192.168.1.1/myfiles/mymenu_{mac}.xml


2.3 XML FormatThe XML data must be well-formed according W3C XML 1.0 specifications. The XML header should be set at the beginning of the XML document. Actually following header variants are supported:

<?xml version="1.0" ?><?xml version="1.0" encoding="UTF-8" ?><?xml version="1.0" encoding="ISO-8859-1" ?>

If the encoding parameter is missing the default encoding is UTF-8 according W3C XML 1.0 specifications.

All XML element names and attribute names are case sensitive.

Special characters must be escape encoded:

Character Name Escape sequence

& Ampersand &

" Quote "

' Apostrophe '

< Left angle bracket <

> Right angle bracket >

2.4 External URI formats

The generic syntax of en external URI is defined by RFC 3986. All external URIs must begin with a scheme name (download protocol), followed by a colon character (":"). Valid URIs witch scheme names for external resources and XML files are:

Page 6 / 50

NOTIFY sip:[email protected]:5060 SIP/2.0Via: SIP/2.0/UDP 192.168.1.101:5060;branch=ad5jh4ut9dsnf3jtf;rportFrom: <sip:[email protected]:5060>;tag=54dg7853c4To: 3030 <sip:[email protected]:5060>Contact: <sip:[email protected]>Call-ID: 65835h8s46f2x429CSeq: 20 NOTIFYEvent: tiptel-xmlContent-Type: application/xmlContent-Length: 140

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneExecute Beep="yes"> <ExecuteItem URI="Led:BACKLIGHT=on"/> </TiptelIPPhoneExecute>


tftp://xxxx/yyy/file.xmlftp://xxxx/yyy/file.xmlhttp://xxxx/yyy/file.cgi?querykey=queryvarhttps://xxxx/yyy/file.php?querykey=queryvarsip:xxxxtel:xxxx

Please note that http URIs with query parameters in XML files must be written in escape encoding (e.g. & → &).

2.4.1 URL variables

Any external URL may contain runtime variables. This variables will be dynamically replaced by the phone with the valid values at runtime shortly before download the resource.

Variable Description

{mac} MAC address of the phone

{ip} Current IP address of the phone

{model} The phone model

{firmware} The firmware version of the phone

{local}or{active_url}

The SIP URI of the default local identity or of the active outgoing identity

{display_local} The display name of the default local identity or of the active outgoing identity

{active_user} The user part of the SIP URI of the default local identity or of the active outgoing call identity

{active_host} The host part of the SIP URI of the default local identity or of the active outgoing identity

{active_key} The function key, line key or SoftKey associated with the URL directive or the call. For coding syntax see the coding of internal URL Key:

{remote} The SIP URI of the remote identity(only in context of PBX sync URL)

{display_remote} The display name of the remote identity(only in context of PBX sync URL)

{call_id} The call-id of the active call(only in context of PBX sync URL)

{duration} The call duration in seconds(only in context of PBX sync URL)

{callDirection} Indication of the call as sender or recipient(only in context of PBX sync URL)

{filter} Search filter of remote XML phonebookExample: http://pbx.ip/php/phonebook/book.php?book=tpb.xml&name={filter}

{search_key} The pressed Key ititated URL query as alphanumeric or URL-escaped code.Example: http://pbx.ip/php/phonebook/book.php?book=tpb.xml&key={search_key}

The variables must be enclosed in curly braces. For historical compatibility instead of braces is allowed to use the dollar sign ( $ ) to mark the the start of variable.

Example:

Page 7 / 50

http://192.168.20.1/cgi-bin/onnewcall.php?from={remote}&to={local}

http://192.168.20.1/cgi-bin/onregister.php?addr=$ip


2.5 Internal call control URI formats

Phones supports some proprietary URI schemas to allow the call control.

– Dial:XXXXXX initiates a new call to the specified phone number/address– SendDigits:XXXXXX generates DTMF tones

2.5.1 Internal URI Dial:

The Dial URI initiates a new call.

URI format:Dial:number

Example:

2.5.2 Internal URI SendDigits:

The SendDigits URI order the phone to send a sequence of DTMF tones. This will be performed only if a connected call exist. The method used to send DTMF tones (In-Band or RFC2833) must be configured for concerned line.

URI format:SendDigits:dtmfDigits

Example:

2.6 Internal device control URI formats

Phones supports some proprietary URI schemas to address internal phone resources and allow the device control.

Page 8 / 50

<?xml version="1.0" ?> <TiptelIPPhoneExecute> <ExecuteItem URI="SendDigits:*8"/> </TiptelIPPhoneExecute>

<?xml version="1.0" ?> <TiptelIPPhoneExecute> <ExecuteItem URI="Dial:004921024280"/> </TiptelIPPhoneExecute>


– Key:XXX emulate a key event– Led:XXX control the LED state– Command: XXX execute commands

2.6.1 Internal URI "Key:"

The internal proprietary URI "Key:" allows to emulate the pressing a button that physically exists on a device.

URI format:Key:XXXXXX

Where XXXXXX variable is one of the following predefined key ids:

Key id Description Example

fkeyNNfkeyNN.0

Emulate the press event of a free programmable function key on the phone device.NN is the number of function key (1 - 12)

Key:fkey5Key:fkey5.0

fkeyNN.M Emulate the key of on an extension moduleNN is the number of a key on module (1 - 27)M is the module number (1 - 3)The specification of the module number is mandatory.

Key:fkey5.1

lineN Emulate the display selection button (line key) to the right of the display.N is the number of selection button (1 - 7)

Key:line2

SoftKeyN Emulate the soft key button below the display.N is the number of soft key button (1 - 4)

Key:SoftKey3

keypadN Emulate numeric keypad button 0-9N is the number of keypad button (0 - 9)

Key:keypad2

star (*) Star button Key:star

pound (#) Pound button Key:pound

increase (+) Increase button Key:increase

decrease (-) Decrease button Key:decrease

cancel (ESC) Escape/Cancel Button Key:cancel

settings (Menu) Settings menu button Key:settings

del (Del) Delete button Key:del

ok (Ok) Ok button Key:ok

up Navigation up key Key:up

down Navigation down key Key:down

left Navigation left key Key:left

right Navigation right key Key:right

directory Directory button Key:directory

mute Mute button Key:mute

rkey R button Key:rkey

redial Redial button Key:redial

speaker Speaker button Key:speaker

alpha_N Alpha keyboard ASCII buttonN is the alpha character

Key:alpha_AKey:alpha_b

space Alpha keyboard space button Key:space

return Alpha keyboard return button Key:return

backspace Alpha keyboard backspace button Key:backspace

Page 9 / 50


Example:

2.6.2 Internal URI "Led:"

The internal proprietary URI "Led:" allows to control the LED status of free programmable function keys on the phone and extension modules, message waiting indicator, as well as display back light.

URI format:Led:XXXXXX=on | off | fastflash | slowflash

Where XXXXXX variable is one of the following predefined key ids:

Key id Description Example

backlight Turns the display back light on / off / ... Led:backlight=on

mwi Turns the message waiting indicator on / off / ... Led:mwi=slowflash

mute Turns the LED on mute button on / off / ... Led:mute=on

speaker Turns the LED on speaker button on / off / ... Led:speaker=fastflash

fkeyNN_CCCfkeyNN.0_CCC

Controls the LEDs of phone function keysNN is the number of function key (1 - 12)CCC is the color value. (red | green | amber)The specification of the module number 0 is optional.

Led:fkey5_red=fastflashLed:fkey5.0_red=fastflashLed:fkey8=offLed:fkey8.0=offLed:fkey8.0_green=off

fkeyNN.s_CCC Supported since Firmware 3.0.0. on phones with colour displaysControls the LED icons of phone selection keys presented on the right side of the display.NN is the number of function key (1 - 6)CCC is the color value. (red | green | amber)The specification of the module number s is mandatory.

Led:fkey1.s_red=fastflashLed:fkey2.s_green=slowflashLed:fkey3.s_green=onLed:fkey3.s_red=offLed:fkey3.s=off

fkeyNN.M_CCC Controls the LEDs of an extension moduleNN is the number of a key on module (1 - 27)M is the module number (1 - 3)CCC is the color value. (red | green | amber)The specification of the module number is mandatory.

Led:fkey5.1_red=fastflashLed:fkey6.1_green=slowflashLed:fkey7.1_green=onLed:fkey8.1_red=offLed:fkey8.1=off

Example:

Page 10 / 50

<?xml version="1.0" ?> <TiptelIPPhoneExecute> <ExecuteItem URI="Led:mwi=slowflash"/> <ExecuteItem URI="Led:backlight=on"/> <ExecuteItem URI="Led:fkey2_red=on"/> <ExecuteItem URI="Led:fkey7.0_green=fastflash"/> <ExecuteItem URI="Led:fkey3.1_green=slowflash"/>  <ExecuteItem URI="Led:fkey1.s_amber=fastflash"/> </TiptelIPPhoneExecute>

<?xml version="1.0" ?> <TiptelIPPhoneExecute> <ExecuteItem URI="Key:fkey2"/> <ExecuteItem URI="Key:line3"/> </TiptelIPPhoneExecute>


2.6.3 Internal URI "Command:"

The internal proprietary URI "Command:" allows to execute service commands.

URI format:Command:XXXXXX

Where XXXXXX variable is one of the following predefined commands:

Command Description Example

Reset Reset the configuration to factory defaults and rebootThe command will be executed only if there are no voice connections.

Command:Reset

Reboot Restart device.The command will be executed only if there are no voice connections.

Command:Reboot

Resync Downloads autoprovisioning files.The command will be executed only if there are no voice connections.

Command:Resync

Lock Lock the phone keys Command:Lock

Unlock Unlock the phone keys Command:Unlock

ClearCallersList Clear local incoming call record list Command:ClearCallersList

ClearRedialList Clear redial list (outgoing call record) Command:ClearRedialList

ClearDirectory Clear local contact list Command:ClearDirectory

Example:

2.6.4 Internal URI "SoftKey:"

Some user interface XML objects support predefined internal URIs.

Available object commands

➢ "SoftKey:Exit " is available for all UI XML objects and redraws the previous XML object present in the phone browser. Does not appear if LockIn set to "yes".

➢ "SoftKey:Select " is available for TiptelPPhoneTextMenu only and calls the URI tag of the selected MenuItem .

➢ "SoftKey:Dial " is available to screens that allow input. The dial string for the "Dial" function is taken from the menu items URI on the Menu Screen.

➢ "SoftKey:Next" is only available in IPPhoneDirectory XML object (Type A).

➢ "SoftKey:Previous" is only available in IPPhoneDirectory XML object (Type A).

Page 11 / 50

<?xml version="1.0" ?> <TiptelIPPhoneExecute> <ExecuteItem URI="Command:ClearRedialList"/> <ExecuteItem URI="Command:ClearCallersList"/> <ExecuteItem URI="Command:Reboot"/> </TiptelIPPhoneExecute>


➢ "SoftKey:Submit " is available for TiptelPPhoneInputScreen only and calls the URL tag .

➢ "SoftKey:Edit_and_Dial " is available to screens that allow input. The dial string for the "Dial" function is taken from the menu items URI on the Menu Screen and copied to the dialing preparation view.

Availability of SoftKeys per object

SoftKey IPPhoneTextMenu IPPhoneTextScreen IPPhoneInputScreen

IPPhoneDirectory (Type A)

Exit x x x x

Select x

Dial x x

Next x

Previous x

Submit x

Edit_and_Dial x x

Custom defined x x x x

SoftKey IPPhoneText IPPhoneDirectory (Type B)

Exit x x

Select x

Dial x

Next

Previous

Submit

Edit_and_Dial x

Custom defined x x

Page 12 / 50


3 XML objects

User interface objects➢ IPPhoneTextMenu (3.3)➢ IPPhoneTextScreen (3.4)➢ IPPhoneInputScreen (3.5)➢ IPPhoneDirectory (Type A) (3.6)➢ IPPhoneStatus (3.7)➢ IPPhoneDirectory (Type B) (3.8)➢ IPPhoneText (3.9)➢ IPPhoneMenu (3.10)

Device control objects➢ IPPhoneConfiguration (3.2)➢ IPPhoneExecute (3.1)➢ IPPhoneDirectory (3.11)

3.1 IPPhoneExecute XML objectThe IPPhoneExecute XML object forces the phone to perform a series of actions. The device executes commands without promoting the user.

XML file description:

XML file example:

Used XML objects

XML object Type Description

TiptelIPPhoneExecute mandatory The root element

Beep optional Set = "yes" to generate a notification beep by phone. Default = "no"

Page 13 / 50

<****IPPhoneExecute Beep = "yes/no" triggerDestroyOnExit=”yes/no”> <ExecuteItem URI="URI"/> <ExecuteItem URI="URI" line="2"/> <!-up to 30 ExecuteItem may follow -></****IPPhoneExecute>

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneExecute Beep="yes/no"> <ExecuteItem URI="http://myserver/notify.php?dev=$mac"/> <ExecuteItem URI="Dial:049116117"/> <ExecuteItem URI="Dial:215" line="3"/> <ExecuteItem URI="Command:Resync/></TiptelIPPhoneExecute>


triggerDestroyOnExit optional Set = "yes" to exit the XML UI view. If the XML object is sent as an answer to a user interface object this will trigger the currently presented UI object to exit if its attribute destroyOnExit is set “yes”. See section 3.14.3 for more details. Default = "no"

ExecuteItem optional Execute item (up to 30 instances)

URI mandatory Any internal or external URI describing the action to be executed. (max. 510 Bytes)

line optional Account to use. If not present or 0 the default account is used

3.2 IPPhoneConfiguration XML objectNot yet implemented.

3.3 IPPhoneTextMenu XML objectThe IPPhoneTextMenu XML object can be used to display a non-formatted menu.


Note: The "****" in "****IPPhoneTextMenu" can be any string, also can be left empty..

XML file example 1: Simple menu

Page 14 / 50

<****IPPhoneTextMenu Beep = "yes/no" LockIn = "yes/no" style = "numbered/none/radio" Timeout = "some integer" cancelAction = "some URI" defaultIndex = "some integer" destroyOnExit = "yes/no" > <Title>any text</Title>

<MenuItem> <Prompt>any Text</Prompt> <URI></URI> <Dial line=”SIP line”></Dial> <Selection></Selection> </MenuItem>

<!-up to 30 MenuItem items may follow --> <!-SoftKey items may be added --></****IPPhoneTextMenu>


XML file example 2: Phone register

XML file example 3: TextMenu user selection

Page 15 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneTextMenu Beep = "yes" style = "numbered"> <Title>Phone register</Title> <MenuItem> <Prompt>Tiptel.com</Prompt> <URI>http://server/more_info_about_tiptel.xml</URI> <Dial>004921024280</Dial> </MenuItem> <MenuItem> <Prompt>My dentist</Prompt> <URI>http://server/info_about_dentist.xml</URI> <Dial line=”2”>00800123412341234</Dial> </MenuItem> <SoftKey index="4"> <Label>Dial</Label> <URI>SoftKey:Select</URI> </SoftKey></TiptelIPPhoneTextMenu>

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneTextMenu Beep = "yes" style = "numbered" Timeout="30"> <Title>Menu</Title> <MenuItem> <Prompt>Item 1</Prompt> <URI>http://server/item_1.xml</URI> </MenuItem> <MenuItem> <Prompt>Item 2</Prompt> <URI>http://server/item_2.xml</URI> </MenuItem></TiptelIPPhoneTextMenu>


When the user selects item 1 and presses soft key 3, the URI requested is http://server/do_handle_selection.php?selection=dataToAppend_1

Notes:• If a "?" already exists in the URI, then a "&" is used to separate the parameters. Note the parameter name

"selection" is always added. If the Selection attribute is omitted, then nothing extra is appended to the URI.• The Selection attribute can contain more than one parameter, for instance, the following selection attribute

is valid <Selection>bla1&action=delete</Selection>Don’t forget to escape encode the attribute for the '&' in the XML file. (→ 2.3)

Used XML objects

XML object Position Type Description

TiptelIPPhoneTextMenu

Root tag Mandatory Root element

Beep Root tag Optional Set = "yes" to generate a notification beep by phone. Default = "no"

style Root tag Optional "numbered", "none" and "radio" indicate the style of the menu. Default is "numbered"

Timeout Root tag Optional If there are no operations from users after entering into the view within the time, the phone will exit to the standby interface. Default is 45 sSee section 3.14.1 for more details.

LockIn Root tag Optional See section 3.14.2 for details. Default is "no".

cancel Action Root tag Optional Defines the URI to be called when the user cancels the view.

defaultIndex Root tag Optional Position of the cursor when the XML object is presented. Default is 1 (valid values: 1..30)

destroyOnExit Root tag Optional “yes” indicates that the object will be removed from the XML browser stack after exit. If not specified or set “no” the object is kept in the XML browser after exit.See section 3.14.3 for more details.

Page 16 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneTextMenu Beep = "yes" style = "numbered" defaultIndex="1"> <Title>Menu</Title> <MenuItem> <Prompt>First selection</Prompt> <URI>http://server/item_1.xml</URI> <Selection>dataToAppend_1</Selection> </MenuItem> <MenuItem> <Prompt>Second selection</Prompt> <URI>http://server/item_2.xml</URI> <Selection>dataToAppend_2</Selection> </MenuItem>

<SoftKey index="3"> <Label>Custom key</Label> <URI>http://server/do_handle_selection.php</URI> </SoftKey></TiptelIPPhoneTextMenu>



Title Body Mandatory Title of menu

MenuItem Body Mandatory Up to 30 items

Prompt MenuItem body Mandatory Text of menu item

URI MenuItem body Optional Internal or external URI describing the action to be executedKeys to start the action:OK/ Cursor right/ SoftKey:Select

Dial MenuItem body Optional The phone will dial out this number.Keys or actions to start dialling:OffHook/ Linekey/ Handfree key/ Headset offhook/ SoftKey:Dial

line Dial body Optional Values 1..8: The phone uses the selected SIP line.Other values or not set: the phone uses the default line.

Selection MenuItem body Optional Custom SoftKey with external URI

SoftKey Optional See section 3.13.1 for detailsNote: Hard keys (3.13.2) cannot be defined for each menu item! Please define them global in the body of the root object.

Label SoftKey Body Mandatory Text of SoftKey

URI SoftKey Body Mandatory Internal or external URI describing the action to be executed

Default soft keys:The following default soft keys will be presented if the XML file of IPPhoneTextMenu does not include any soft key description:

SoftKey index Name URI

1 Exit SoftKey:Exit

4 Select SoftKey:Select

Key processing:

Key Function description

Cursor up/down Move focus in list up/down

Digit key 1-9, 0 Select menu item whose index value equals to number's key press and dial the the corresponding number in <Dial>. If there is no <dial> entry call the URI.Note: if any hard key “0”...”9” is setup with an URL (see 3.13.2) the above type of selection is disabled.

1-9, 0, *, # If hard keys are user defined, URI is executed. (See 3.13.2)

SoftKey "Dial" Dial the corresponding number in <Dial> of the selected menu item.

SoftKey "Edit_and_Dial" Copies the corresponding number in <Dial> of the selected menu item into

Page 17 / 50



dialing preparation view. There the user can edit the number and dial the number.

Selection keys Select the corresponding menu item and dial the the corresponding number in <dial>. If there is no <dial> entry call the URI.

Cursor right Dial the the corresponding number of the selected menu item. If there is no <Dial> entry call the URI.

SoftKey "Select" Call corresponding URI command of the selected menu item.

SoftKey "Exit" Present previous displayed xml view if available. Else return to idle screen.

Cursor left same function as SoftKey "Exit"

Esc Return to idle screen. If 'cancelAction' is defined the URI is executed.If 'cancelAction" calls another UI XML object the previous view is kept on the stack.

Ok If LockIn is set "no", the function of the "OK" key will be the same as SoftKey "Select", if it is "yes", there will be no response

OffHook/ Linekey/ Handfree key/ Headset offhook

If LockIn is set "no", the function of the key will be the same as SoftKey "Dial", if it is "yes", there will be no response.

3.4 IPPhoneTextScreen XML objectThe IPPhoneTextScreen XML object can be used to display a non-formatted text in a scrollable window.


Note: The "****" in "****IPPhoneTextScreen" can be any string, also can be left empty..

XML file example 1:

Page 18 / 50

<****IPPhoneTextScreen Beep = "yes/no" LockIn = "yes/no" Timeout = "some integer" cancelAction = "some URI" doneAction = "some URI" destroyOnExit = "yes/no" > <Title>any text</Title> <Text>any text</Text> <!-SoftKey items may be added --></****IPPhoneTextScreen>


XML file example 2: user defined soft keys and hard keys

Used XML objects


TiptelIPPhoneTextScreen


Beep Root tag Optional Set = "yes" to generate a notification beep by phone. Default is "no"


Page 19 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneTextScreen Beep = "yes"> <Title>Title of screen</Title> <Text>Text of screen\nthis was a manually set newline</Text>

<SoftKey index="3"> <Label>Custom key</Label> <URI>http://myserver2.de/get_it.php</URI> </SoftKey></TiptelIPPhoneTextScreen>

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneTextScreen Beep = "yes"> <Title>Title of screen</Title> <Text>Press 0..9 to search name in all phone books.</Text>

<SoftKey name="0"> <URI>http://myserver2.de/get_pb.php?key=0</URI> </SoftKey> <SoftKey name="9"> <URI>http://myserver2.de/get_pb.php?key=9</URI> </SoftKey> <SoftKey name="#"> <URI>http://myserver2.de/get_pb.php?key=B</URI> </SoftKey> <SoftKey name="*"> <URI>http://myserver2.de/get_pb.php?key=A</URI> </SoftKey> <SoftKey index="1"> <Label>Custom key 1</Label> <URI>http://myserver2.de/get_it.php?opt=1</URI> </SoftKey> <SoftKey index="2"> <Label>Custom key 2</Label> <URI>http://myserver2.de/get_it.php?opt=2</URI> </SoftKey></TiptelIPPhoneTextScreen>




cancel Action Root tag Optional Defines the URI to be called when the user cancels the view.

doneAction Root tag Optional Defines the URI to be called when the user acknowlegdes the view with 'Ok'-Key.


Title Body Mandatory The title of text notes

Text Body Mandatory The text to be displayed

SoftKey Optional See section 3.13.1 for details

Default soft keys:The following default soft key will be presented if the XML file of IPPhoneTextScreen does not include any soft key description:


1 Exit SoftKey:Exit

Key processing:


Cursor up/down Scrolling in text up/down


Esc Return to idle screen. If 'cancelAction' is defined the URI is executed. If 'cancelAction" calls another UI XML object the previous view is kept on the stack.

Ok Present previous displayed xml view if available. Else return to idle screen.If 'doneAction' is defined the URI is executed.If 'doneAction" calls another UI XML object the previous view is kept on the stack.


3.5 IPPhoneInputScreen XML object


Page 20 / 50


XML file example:

Page 21 / 50

<****IPPhoneInputScreen Beep = "yes/no" LockIn = "yes/no" Timeout = "some integer" type = "IP/string/number/timeInt/dateInt" password = "yes/no" editable = "yes/no" cancelAction = "some URI" defaultIndex = "1" destroyOnExit = "yes/no" > <Title>any text</Title> <Prompt>any text</Prompt> <URL>target receiving the input</URL> <Parameter>name of param added to URL</Parameter> <Default>default value</Default>

<InputField type = "IP/string/number/timeInt/dateInt" password = "yes/no" editable = "yes/no" > <Prompt>local any text</Prompt> <URL>local target receiving the input</URL> <Parameter>local name of param added to URL</Parameter> <Default>local default value</Default> <Selection>selection</Selection> <!-SoftKey items may be added --> </InputField>

<!-up to 6 InputField items may be added --> <!-SoftKey items may be added --></****IPPhoneInputScreen>


Note: In this example, when the user presses "Ok" or "SoftKey:Submit" on the phone after entering "frank" for user and "2222" for code, the phone will call the following URLs:

➢ http://myserver/action.php?User=frank&Code=2222&time=12:34&date=23.10.2012&selection=1, if the "Ok" key is pressed while editing the "User" field,

➢ http://myserver/action.php?User=frank&Code=2222&time=12:34&date=23.10.2012&selection=2, if the "Ok" key is pressed while editing the "Code" field.

Used XML objects:


TiptelIPPhoneInputScreen



type Root tag Mandatory Specifies the type of input. Posible values are: "IP", "string", "number", "timeInt" and "dateInt"Default is "string"The type “number” includes integers plus * and #

password Root tag Optional Specifies if the input is masked by '*' characters. Default is "no"

editable Root tag Optional Specifies if the user is allowed to modify the input. Default is "no"

Page 22 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneInputScreen Timeout="180" type="string" cancelAction="http://myserver/cancel_action.php"> <Title>I'm the title</Title> <Prompt>Guidance</Prompt> <URL>http://myserver/action.php</URL> <InputField type="string" editable="yes" > <Prompt>User</Prompt> <Parameter>User</Parameter> <Default>Default 11111111111111</Default> <Selection>1</Selection> </InputField> <InputField type="number" editable="yes" > <Prompt>Code</Prompt> <Parameter>Code</Parameter> <Default></Default> <Selection>2</Selection> </InputField> <InputField type="timeInt" editable="yes" > <Prompt>input 3</Prompt> <Parameter>time</Parameter> <Default>12:34</Default> <Selection>3</Selection> </InputField> <InputField type="dateInt" editable="yes" > <Prompt>input 4</Prompt> <Parameter>date</Parameter> <Default>23.10.2012</Default> <Selection>4</Selection> </InputField></TiptelIPPhoneInputScreen>





Cancel Action Root tag Optional Defines the URI to be called when the user cancels the view.

defaultIndex Root tag Optional Default is 1 (valid values: 1..6)



Prompt Body Optional The text to be displayed. Value is used as default for each input field

URL Body Mandatory URI is called when user completes the input with "Ok" or "SoftKey:Submit".

Parameter Body Optional The parameter name following the URL, i.e. URL?Parameter setting name=user input contentsValue is used as default for each input field

Default Body Optional The default input content.Value is used as default for each input field

SoftKey InputField tag Optional See section 3.13.1 for details

Inputfield Body Mandatory Up to 6 items

type InputField tag Mandatory Specifies the type of input. Posible values are: "IP", "string", "number", "timeInt" and "dateInt"Default is "string"Overrides the value set in the root tag.

password InputField tag Optional Specifies if the input is masked by '*' characters. Default is "no"

editable InputField tag Optional Specifies if the user is allowed to modify the input. Default is "no"

Prompt InputField tag Optional The text to be displayed. Value is used as default for each input field

Parameter InputField tag Optional The parameter name following the URL, i.e. URL?Parameter setting name=user input contents

Default InputField tag Optional The default input content.

Selection InputField tag Optional Add selection=preset parameter after http address when sending request if the SoftKey URI is the server’s http address. e.g. http://server.com/input.php?Selection=1

SoftKey InputField tag Optional See section 3.13.1 for details

Default soft keys:

Page 23 / 50


The following default soft keys will be presented if the XML file of IPPhoneInputScreen does not include any soft ley description:Note: the name varies according the default language of the phone

Default soft keys: type = IP


1 Exit SoftKey:Exit

2 . SoftKey:Dot

3 <-- SoftKey:BackSpace

4 Ok SoftKey:Submit

Default soft keys:type = number


1 Exit SoftKey:Exit


4 Ok SoftKey:Submit

Default soft keys:type = string


1 Exit SoftKey:Exit

2 2ab, 123,... SoftKey:ChangeMode (no function on phone with alpha keyboard)


4 Ok SoftKey:Submit

5 . SoftKey:Dot

6 space SoftKey:NextSpace

Default soft keys: type = time, date


1 Exit SoftKey:Exit

4 Ok SoftKey:Submit

Key processing:



"SoftKey:Exit" Present previous displayed xml view if available. Else return to idle screen.


Ok, "SoftKey:Submit" If LockIn is set "no", the function of the"OK" key is the same as "SoftKey:Submit". If it is "yes", there will be no response

Page 24 / 50



Digit key 1-9, 0Alpha key, +, -

If input field is selected

Backspace, "SoftKey:BackSpace"

Space, "SoftKey:NextSpace"

"SoftKey:Dot" Add "." at the cursor’s position on the focused-on item.

"SoftKey:Colon" Add ":" at the cursor’s position on the focused-on item.

"SoftKey:ChangeMode" Change of keyset depending on type of input field. (no function on phone with alpha keyboard)

3.6 IPPhoneDirectory XML object (Type A)The IPPhoneDirectory XML object can be used to display a simple phone register. Since the term “IPPhoneDirectory” is used in several XML objects the phone auto detects the correct application.


Note: The "****" in "****IPPhoneDirectory" can be any string, also can be left empty..

XML file example:

Page 25 / 50

<****IPPhoneDirectory Beep = "yes/no" LockIn = "yes/no" style = "numbered/none" Next = "http://myserver.de/next_page.php" Previous = "http://myserver.de/previous_page.php" Timeout = "some integer" cancelAction = "some URI" destroyOnExit = "yes/no" >

<Title>any text"</Title>

<MenuItem> <Prompt>Contact Name</Prompt> <URI>number</URI> </MenuItem>

<!-Additional menu items may be added - -> <!-SoftKey items may be added - -></****IPPhoneDirectory>


Used XML objects:


TiptelIPPhoneDirectory



style Root tag Optional "numbered" or "none" indicate the style of the menu. Default is "numbered"

Next Root tag Optional The corresponding URI of SoftKey "Next"

Previous Root tag Optional The corresponding URI of SoftKey "Previous"



Cancel Action Root tag Optional Defines the URI to be called when the user cancels the view.

destroyOnExit Root tag Optional “yes” indicates that the object will be removed from the XML browser stack after exit. If not specified or set “no” the object is kept in the XML browser after exit.

Page 26 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneDirectory Next = "http://myserver.de/next_page.xml" Previous = "http://myserver.de/previous_page.xml" > <Title>Title of directory"</Title> <MenuItem> <Prompt>Tiptel.com</Prompt> <URI>021024280</URI> </MenuItem> <SoftKey index="1"> <Label>Exit</Label> <URI>SoftKey:Exit</URI> </SoftKey> <SoftKey index="2"> <Label>Previous</Label> <URI>SoftKey:Previous</URI> </SoftKey> <SoftKey index="3"> <Label>Next</Label> <URI>SoftKey:Next</URI> </SoftKey> <SoftKey index="4"> <Label>Dial</Label> <URI>SoftKey:Dial</URI> </SoftKey> <SoftKey index="8"> <Label>plus</Label> <URI>SoftKey:Edit_and_Dial</URI> </SoftKey></TiptelIPPhoneDirectory>

http://myserver.de/previous_page.xml



See section 3.14.3 for more details.


MenuItem Body Mandatory Up to 15 items

Prompt MenuItem Body Mandatory The text to be displayed

URI MenuItem Body Mandatory Phone number or IP-Address to be dialed

SoftKey Optional See section 3.13.1 for details

Label SoftKey Body Mandatory Text of SoftKey

URI SoftKey Body Mandatory Internal or external URI describing the action to be executed

Default soft keys:The following default soft keys will be presented if the XML file of IPPhoneDirectory does not include any soft key description:


1 Exit SoftKey:Exit

2 Previous The URI specified by "Previous" in the root tag of the XML -object IPPhoneDirectory

3 Next The URI specified by "Next" in the root tag of the XML -object IPPhoneDirectory

4 Dial SoftKey:Dial

8 plus SoftKey:Edit_and_Dial

Key processing:



Digit key 1-9, 0 Select menu item whose index value equals to number's key press and dial the the corresponding number. Note: if any hard key “0”...”9” is setup with an URL (see 3.13.2) the above type of selection is disabled.


SoftKey "Dial" Dial the corresponding number of the selected menu item.

SoftKey "Edit_and_Dial" Copies the corresponding number of the selected menu item into dialing preparation view. There the user can edit the number and dial the number.

Selection keys same function as SoftKey "Dial"

SoftKey "Previous", SoftKey "Next" Call the URI command in "Previous"/ "Next"




Page 27 / 50



Ok If LockIn is set "no", the function of the "OK" key will be the same as SoftKey "Dial", if it is "yes", there will be no response


If LockIn is set "no", the function of the key will be the same as SoftKey "Dial", if it is "yes", there will be no response.

3.7 IPPhoneStatus XML objectThe IPPhoneStatus XML object can be used to display messages via Push XML. There are two output modes:

➢ Presentation in a tree view in full screen mode➢ Presentation in status area on idle screen


Note: The "****" in "****IPPhoneStatus" can be any string, also can be left empty..

XML file example: Full screen presentation of all messages in a scrollable tree view.

XML file example: Removing message with index 0

XML file example: presentation of maximum one message in status area on idle screen

Page 28 / 50

<****IPPhoneStatus Beep = "yes/no" Embedded = "yes/no" triggerDestroyOnExit = "yes/no"> <Session>Any Session ID</Session> <Message index="index" type="alert" Timeout="timeout in s" >Message text </Message> <!-Up to 10 message items may be added - -></****IPPhoneStatus>

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneStatus Beep="yes"> <Message index="0">I'm the message text</Message> <Message index="4" type="alert" Timeout="60">this is message 4 </Message></TiptelIPPhoneStatus>

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneStatus Beep="yes"> <Message index="0"></Message></TiptelIPPhoneStatus>


If the message does not fit to the output area the full message can be seen after pressing soft key “Messages”1 in the full screen presentation.

Used XML objects:


TiptelIPPhoneStatus Root tag Mandatory Root element


Embedded Root tag Optional Set = "yes" to present message index=”0” on idle screen. Default is "no"Messages with other indexes will not be presented on idle screen!

triggerDestroyOnExit Root tag Optional If this XML object is sent with triggerDestroyOnExit = “yes” while an UI XML object with an attribute destroyOnExit = “yes” is visible the UI XML object is triggered to exit. If no other UI XML object is on the stack which has to be presented the IPPhoneStatus XML object is presented.See section 3.14.3 for more details.

Session Body Optional Session Id can be any string. Session ID used to identify the application displaying message. It allows message change and message reset.

Message Body Mandatory Message to be displayed or empty to reset the message. Up to 10 items

index Message Body Mandatory Index of the message for the session, the index starts at 0.

type Message Body Optional Type of message, only "alert" is supported. If not specified the message stays on the screen until it is reset by an empty message or exiting the screen with SoftKey:Exit

Timeout Message Body Optional Timeout of the "alert" message, overrides the 3s default value.

Default soft keys:The following soft keys will be presented:


1 Exit SoftKey:ExitReturns to the standard idle screen.

Key processing:

1 Labelling of soft key according current language setting.

Page 29 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneStatus Beep="yes" Embedded="yes"> <Message index="0">This message is presented\non the idle screen</Message> </Message></TiptelIPPhoneStatus>



Cursor up/down Scrolling in text messages up/down

SoftKey "Exit", Esc, Ok Returns to standard idle screen. The internal list of messages is not removed and will be shown again if any content of the list is changed.

3.8 IPPhoneDirectory XML object (Type B)The IPPhoneDirectory XML object can be used to display a simple phone register. Since the term “IPPhoneDirectory” is used in several XML objects the phone auto detects the correct application.This XML object is supported since Firmware 2.0.65.


Note: The "****" in "****IPPhoneDirectory" can be any string, also can be left empty..

XML file example:

Page 30 / 50

<****IPPhoneDirectory track = "yes/no" >

<Title>any text"</Title>

<DirectoryEntry> <Name>Contact Name</Name> <Telephone>number</Telephone> </DirectoryEntry>

<!-Additional directory entries may be added - -> <!-SoftKeyItem items may be added - -></****IPPhoneDirectory>


Used XML objects:


IPPhoneDirectory Root tag Mandatory Root element

track Root tag Optional “no” indicates that the object will be removed from the XML browser stack after exit. If not specified or set “yes” the object is kept in the XML browser after exit.


DirectoryEntry Body Mandatory Up to 500 items

Name DirectoryEntry Body Mandatory The text to be displayed

Telephone DirectoryEntry Body Mandatory Phone number to be dialed

SoftKeyItem Optional See section 3.13.3 for details

Name SoftKeyItem Body Mandatory Addresses the SoftKey or Hardkey

Label SoftKeyItem Body Mandatory Text of SoftKeyItem

URL SoftKeyItem Body Mandatory Internal or external URL describing the action to be executed

Default soft keys:The following default soft keys will be presented if the XML file of IPPhoneDirectory does not include any SoftKeyItem description:


1 Exit SoftKey:Exit

3 plus SoftKey:Edit_and_Dial

Page 31 / 50

<?xml version="1.0" encoding="UTF-8"?> <IPPhoneDirectory> <Title>Title of directory"</Title> <DirectoryEntry> <Name>Tiptel.com</Name> <Telephone>021024280</Telephone> </DirectoryEntry> <DirectoryEntry> <Name>Police</Name> <Telephone>110</Telephone> </DirectoryEntry>

<SoftKeyItem> <Name>F1</Name> <Label>exit</Label> <URL>SoftKey:Exit</URL> </SoftKeyItem> <SoftKeyItem> <Name>1</Name> <Label>exit</Label> <URL>http://myserver.com/phones/phonebook.php?key=1</URL> </SoftKeyItem></IPPhoneDirectory>



4 Dial SoftKey:Dial

Key processing:



Digit key 1-9, 0 Select menu item whose index value equals to number's key press and dial the the corresponding number. Note: if any hard key “0”...”9” is setup with an URL (see 3.13.3) the above type of selection is disabled.


SoftKey "Dial" Dial the corresponding number of the selected menu item.

SoftKey "Edit_and_Dial" Copies the corresponding number of the selected menu item into dialing preparation view. There the user can edit the number and dial the number.

Selection keys same function as SoftKey "Dial"



Esc Return to previous or idle screen.

Ok Dial the corresponding number of the selected menu item.


Dial the corresponding number of the selected menu item.

3.9 IPPhoneText XML objectThe IPPhoneText XML object can be used to display a non-formatted text in a scrollable window. This XML object is supported since Firmware 2.0.65.


Note: The "****" in "****IPPhoneText" can be any string, also can be left empty..

XML file example: user defined soft keys and hard keys

Page 32 / 50

<****IPPhoneText track = "yes/no">

<Title>any text</Title> <Text>any text</Text> <!-SoftKeyItem items may be added --></****IPPhoneText>


Used XML objects


TiptelIPPhoneText Root tag Mandatory Root element

track Root tag Optional “no” indicates that the object will be removed from the XML browser stack after exit. If not specified or set “yes” the object is kept in the XML browser after exit.


Text Body Mandatory The text to be displayed


Default soft keys:The following default soft key will be presented if the XML file of IPPhoneTextScreen does not include any soft key description:


1 Exit SoftKey:Exit

Key processing:



SoftKey "Exit" Present previous displayed XML view if available. Else return to idle screen.

Page 33 / 50

<?xml version="1.0" encoding="UTF-8"?> <IPPhoneText> <Title>Title of screen</Title> <Text>Press *, # to search name in all phone books.</Text> <SoftKeyItem> <Name>#</Name> <URL>http://myserver2.de/get_pb.php?key=B</URL> </SoftKeyItem> <SoftKeyItem> <Name>*</Name> <URL>http://myserver2.de/get_pb.php?key=A</URL> </SoftKeyItem> <SoftKeyItem> <Name>F1</Name> <Label>Softkey 1</Label> <URL>http://myserver2.de/get_it.php?opt=1</URL> </SoftKeyItem> <SoftKeyItem> <Name>F2</Name> <Label>Softkey 2</Label> <URL>http://myserver2.de/get_it.php?opt=2</URL> </SoftKeyItem></IPPhoneText>



Esc Return to idle screen.

Ok Present previous displayed XML view if available. Else return to idle screen.


3.10 IPPhoneMenu XML objectThe IPPhoneMenu XML object can be used to display a non-formatted menu in a scrollable window. This XML object is supported since Firmware 3.1.1.


Note: The "****" in "****IPPhoneMenu" can be any string, also can be left empty..

XML file example:

Used XML objects


TiptelIPPhoneMenu Root tag Mandatory Root element

track Root tag Optional “no” indicates that the object will be removed from the XML browser stack after exit.

Page 34 / 50

<****IPPhoneMenu track = "yes/no">

<Title>any text</Title> <MenuItem> <Name>name of menu item</Name> <URL>to be called</URL> </MenuItem> <!-SoftKeyItem items may be added --></****IPPhoneMenu>

<?xml version="1.0" encoding="UTF-8"?> <IPPhoneMenu> <Title>Title of screen</Title> <MenuItem> <Name>first menu item</Name> <URL>http://myserver2.de/get_it.php?opt=1</URL> </MenuItem> <MenuItem> <Name>second menu item</Name> <URL>http://myserver2.de/get_it.php?opt=2</URL> </MenuItem></IPPhoneMenu>



If not specified or set “yes” the object is kept in the XML browser after exit.


MenuItem Body Mandatory The text to be displayed

Name MenuItem body Mandatory Text of menu item

URL MenuItem body Optional Internal or external URL describing the action to be executedKeys to start the action:OK/ Cursor right


Default soft keys:The following default soft keys will be presented if the XML file of IPPhoneMenu does not include any soft key description:


1 Exit SoftKey:Exit

4 Select SoftKey:Select

Key processing:



SoftKey "Exit" Present previous displayed XML view if available. Else return to idle screen.

Esc Return to idle screen.

SoftKey "Select" Call corresponding URI command of the selected menu item.

Ok Present previous displayed XML view if available. Else return to idle screen.


3.11 External XML phone bookThe phone provides a build-in service to merge an external XML phone book in to internal phone book. For historical compatibility reasons the XML notation reuses the root element ***IPPhoneDirectory.


Page 35 / 50


XML file example:

Used XML objects


PbookIPPhoneDirectory mandatory The root element

DirectoryEntry optional Directory item (up to 30 instances)

Name mandatory Label of the entry (max. 32 UTF8 chars)

Telephone mandatory Phone number or SIP address to be dialed (max. 126 Bytes)

3.12 XML Device InfoThe phone provides device information in a XML file on request with HTTP GET Service URL "device info".


Page 36 / 50

<?xml version="1.0" encoding="UTF-8"?> <PbookIPPhoneDirectory> <DirectoryEntry> <Name>Bob</Name> <Telephone>+49116117</Telephone> </DirectoryEntry> <DirectoryEntry> <Name>Alice</Name> <Telephone>[email protected]</Telephone> <Telephone>[email protected]</Telephone> </DirectoryEntry></PbookIPPhoneDirectory>

<****IPPhoneDirectory> <DirectoryEntry> <Name>The name of the entry</Name> <Telephone>The telephone number</Telephone> <Telephone>Optional 2. telephone number</Telephone> <Telephone>Optional 3. telephone number</Telephone> </DirectoryEntry> <!-up to 1000 DirectoryEntries may follow -></***IPPhoneDirectory>

<TiptelIPPhoneDeviceInfo> <Firmware>Firmware Version X.Y.Z</Firmware> <Vendor>Tiptel</Vendor> <Device>Model abeviation</Device> <MAC>MAC-Address</MAC> <SipUser1>SIP User name</SipUser1></TiptelIPPhoneDeviceInfo>


XML file example:

Used XML objects


TiptelIPPhoneDeviceInfo mandatory The root element

Firmware mandatory Firmware Version Major.Minor.Revisioin

Vendor mandatory Vendor string “Tiptel” or OEM-String

Device mandatory Model string

MAC mandatory MAC Address

SipUser1 optional SIP Account 1, user name

3.13 Sub objects for UI XML objects

3.13.1 Sub object "SoftKey" for XML UI objects

The SoftKey object can be used to override the default soft keys in some user interface (UI) XML objects: ➢ IPPhoneTextMenu (3.3)➢ IPPhoneTextScreen (3.4)➢ IPPhoneInputScreen (3.5)➢ IPPhoneDirectory (Type A) (3.6)

It allows developers to link arbitrary URIs to keys in the XML screens and invoke soft key behavior native to each XML screen type. The phone has two layers with four soft keys. The user can toggle the soft key layer with the lowermost select key on the right side of the display if an arrow is shown right of the forth soft key..

Notes:• custom soft keys are only available for the UI XML objects.• if you use custom soft keys, the default soft keys of the XML object are not displayed anymore. This means

they have to be recreated as custom soft eys.• The texts/labels of internal soft keys change if the language of the user interface changes. Predefined

internal URIs are listed in 2.6.4 .• The soft key object is also used for custumizing a selection of hard keys. See section 3.13.2 for details.


Page 37 / 50

<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneDeviceInfo> <Firmware>2.0.0</Firmware> <Vendor>Tiptel</Vendor> <Device>t3130</Device> <MAC>000CC4300087</MAC> <SipUser1>201</SipUser1></TiptelIPPhoneDeviceInfo>


Used XML objects


SoftKey Body Optional

index SoftKey root tag Optional Indicates the SoftKey numbervalid values: 1-8If "index" is skipped then the defined SoftKeys get indexes automatically starting at index 1.

name SoftKey root tag Optional Indicates setting up a hard key. See section 3.13.2 for details.If the attribute “name” is not set a regular soft key is assumed.

Label SoftKey Body Mandatory if index is set

Text of SoftKey

URI SoftKey Body Mandatory Soft key: Internal URI (2.6.4) or external URI describing the action to be executedHard key: External URI describing the action to be executed

3.13.2 Using the internal object "SoftKey” for customizing hard keys

For some applications there is the need to call URLs by pressing the keys 0-9, '#', '*' or others. This feature is available in the following objects:

➢ IPPhoneTextMenu (3.3)➢ IPPhoneTextScreen (3.4)➢ IPPhoneInputScreen (3.5)➢ IPPhoneDirectory (Type A) (3.6)


Used XML objects


SoftKey Body Optional

Page 38 / 50

<SoftKey name = "key"> <URI>any external uri</URI></SoftKey>

<SoftKey index = "1-8" name="key"> <Label>text</Label> <URI>any uri</URI></SoftKey>



name SoftKey root tag Optional Indicates setting up a hard key. The supported hard keys are listed in Table 1: Customizable hard keys in object“SoftKey”

URI SoftKey Body Mandatory External URI describing the action to be executed

An example can be found in 3.4

Since Firmware 1.1.23 Since Firmware 3.1.1

“0”, “1”,..., “9”, “#”, “*” “0”, “1”,..., “9”, “#”, “*”

UPDOWNLEFTRIGHTOKESCDELMENUDIRECTORYNEWDIRECTORYREDIALMUTESPEAKERRKEYVOL_UPVOL_DOWN

Table 1: Customizable hard keys in object “SoftKey”

3.13.3 Sub object "SoftKeyItem" for XML UI objects (Type B)

The SoftKeyItem object can be used to override the default soft keys in user interface (UI) XML objects IPPhoneText (3.9), IPPhoneDirectory (3.8) and IPPhoneMenu (3.10). It allows developers to link arbitrary URIs to keys in the XML screens and invoke soft key behavior native to each XML screen type. The phone has two layers with four soft keys. The user can toggle the soft key layer with the lowermost select key on the right side of the display if an arrow is shown right of the forth soft key..

Notes:• custom SoftKeyItems are only available for the above mentioned UI XML objects.• if you use custom SoftKeyItems, the default SoftKeyItems of the XML object are not displayed anymore.

This means they have to be recreated as custom SoftKeyItems.• The texts of internal SoftKeyItems change if the language of the user interface changes. Predefined internal

URIs are listed in 2.6.4.• The SoftKeyItem object is also used for customizing a selection of hard keys.


Page 39 / 50


Used XML objects


SoftKeyItem Body Optional

Name SoftKeyItem root tag Mandatory Adresses the key:➢ Soft keys (first layer) F1..F4➢ Soft keys (second layer) F5..F8➢ The supported hard keys are listed in Table 2:

Customizable hard keys in object “SoftKeyItem”

Label SoftKeyItem Body Mandatory Text of SoftKeyItem

URI SoftKeyItem Body Mandatory Soft key: Internal URI (2.6.4) or external URI describing the action to be executedHard key: External URI describing the action to be executed

Since Firmware 2.0.65 Since Firmware 3.1.1

“0”, “1”,..., “9”, “#”, “*” “0”, “1”,..., “9”, “#”, “*”

UPDOWNLEFTRIGHTOKESCDELMENUDIRECTORYNEWDIRECTORYREDIALMUTESPEAKERRKEYVOL_UPVOL_DOWN

Table 2: Customizable hard keys in object “SoftKeyItem”

3.14 Special attributes for UI XML objects

3.14.1 Timeout

The Timeout attribute is an optional root tag attribute for all of the current UI XML objects. When the phone receives an XML object with this attribute set it will override the default 45 seconds timeout specified for custom

Page 40 / 50

<SoftKeyItem> <Name>addresses the soft key or hard key</Name> <Label>text</Label> <URI>any internal or external uri</URI></SoftKeyItem>


applications.Setting Timeout to "0" will disable the timeout feature.This timeout is reset by button presses.

3.14.2 LockIn

The LockIn attribute is an optional root tag attribute for all of the current UI XML objects. This attribute allows the XML designer to specify that a screen can not be cancelled.When a phone receives an UI XML object with the attribute set to "yes" it ignores all events that would cause the screen to exit without using the keys defined by the object.Default is "no".

Setting LockIn will disable the default timeout feature (45 seconds) unless the Timeout attribute is also set in the root tag.

Note: An incoming call still cancels the "locked" screen.

3.14.3 triggerDestroyOnExit/ destroyOnExit

The triggerDestroyOnExit is an optional root tag attribute for IPPhoneExecute. Its default value is “no”.

By default, if a UI XML object receives a non-UI XML object as an answer to an exit URI or URL the UI XML object is not destroyed and stays on the phone display even its destroyOnExit tag is set to “yes”.

By setting triggerDestroyOnExit to “yes” the previous UI XML object is removed if its destroyOnExit tag is set to “yes”.

Page 41 / 50


4 HTTP API

4.1 HTTP GET Device control URLs

Action URL /cgi-bin/remote/devctl?minibrowserurl=<url>

Make call /cgi-bin/remote/devctl?makecall=<number>&line=<id>

Drop activ call /cgi-bin/remote/devctl?drop

Reboot /cgi-bin/remote/devctl?reboot

Make screenshot /cgi-bin/remote/devctl?screenshot

Example: Make call using browser URL to Number 110 using SIP-Account 2

4.2 HTTP GET Service URLs

Device Info (FW. 1.2.25 or later) /service/devinfo.xml?CgiServiceAPI=XmlDeviceInfo

SIP Trace File /cgi-bin/webcgi/sip.txt?CgiServiceAPI=Siptrace

Wireshark network traffic trace /cgi-bin/webcgi/net.pcap?CgiServiceAPI=PCAP

Syslog trace /cgi-bin/webcgi/trace.tar?CgiServiceAPI=Syslog

Significant device events log files /cgi-bin/webcgi/devlogs.tar?CgiServiceAPI=Phonelog

Startup log file /cgi-bin/webcgi/boot.txt.gz?CgiServiceAPI=Bootlog

Download screenshots /cgi-bin/webcgi/screenshots.tar?CgiServiceAPI=Screenshots

Page 42 / 50

http://192.168.1.100/cgi-bin/remote/devctl?makecall=110&line=2


5 HOW TO

5.1 HOW TO push XML file via HTTP

Phone IP: 192.168.1.30XML file to push: ./push.xml"

5.2 HOW TO push XML file on Asterisk via SIP NOTIFY

Add to the Asterisk configuration file /etc/asterisk/sip_notify.cfg the XML event.

To send the XML data to phone address 2011 enter on CLI

Note: You must reload the configuration file for the changes to take effect if Asterisk is already running*CLI> config reload /etc/asterisk/sip_notify.conf

Page 43 / 50

#!/bin/sh

postfile="./push.xml"response="./result.htm"pushurl="http://192.168.1.30/xmlservice"addhdr="Content-Type: text/xml"usr=adminpw=admin

wget -–user $usr –-password $pw -O ${response} --header "${addhdr}" --post-file ${postfile} $pushurl

[tiptel-xmlexec-reboot]Event=>tiptel-xmlContent-type=>application/xmlContent=><?xml version="1.0" encoding="UTF-8"?>Content=><TiptelIPPhoneExecute Beep="yes">Content=><ExecuteItem URI="Command:Reboot"/>Content=></TiptelIPPhoneExecute>Content=>

*CLI> sip notify tiptel-xmlexec-reboot 2011


5.3 HOW TO trigger remote action URL via HTTP

Phone IP: 192.168.1.30HTTP Server IP: 192.168.1.1

Note: Although the URL Variable {ip} use brace notation wget will convert it to proper hex codes before send to device.

5.4 HOW TO trigger remote action URL on Asterisk via SIP NOTIFY

Add to the Asterisk configuration file /etc/asterisk/sip_notify.cfg the XML event.

To trigger the XML service on device 5566 enter on CLI

Page 44 / 50

#!/bin/sh

response="./result.htm"aurl="http://192.168.1.1/tiptel3020xml/TestAction.php?devip={ip}"phoneurl="http://192.168.1.30/cgi-bin/remote/devctl?minibrowserurl="$aurlusr=adminpw=admin

wget -–user $usr –-password $pw -O ${response} $phoneurl

[tiptel-xmlremote]Event=>tiptel-actionurlContent-type=>text/plainContent=>http://192.168.1.1/tiptel3020xml/TestAction.php?dev={mac}&addr={ip}Content=>

*CLI> sip notify tiptel-xmlremote 5566


6 XML Schema, XSL Model

<?xml version="1.0" encoding="ISO-8859-1" ?><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:simpleType name="textAttributeYesNo"> <xs:restriction base="xs:string"> <xs:pattern value="yes|no" /> </xs:restriction></xs:simpleType>

<xs:simpleType name="textURI"> <xs:restriction base="xs:string"> <xs:maxLength value="510"/> <xs:minLength value="1"/> </xs:restriction></xs:simpleType>

<xs:simpleType name="textPhoneNr"> <xs:restriction base="xs:string"> <xs:maxLength value="126"/> <xs:minLength value="1"/> </xs:restriction></xs:simpleType>

<xs:element name="TiptelIPPhoneExecute"> <xs:complexType> <xs:sequence> <xs:element name="ExecuteItem" minOccurs="0" maxOccurs="30"> <xs:complexType> <xs:attribute name="URI" type="textURI" /> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="Beep" type="textAttributeYesNo" default="no" /> </xs:complexType></xs:element>

<xs:element name="PbookIPPhoneDirectory"> <xs:complexType> <xs:sequence> <xs:element name="DirectoryEntry" minOccurs="0" maxOccurs="1000"> <xs:complexType> <xs:sequence> <xs:element name="Name" minOccurs="1"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:maxLength value="32"/> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Telephone" type="textPhoneNr" minOccurs="1" maxOccurs="3" /> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType></xs:element>

Page 45 / 50


</xs:schema>

7 HistoryDoc Version

Date Firmware

Chapter Changes

1.1 24.05.2013 1.1.40 3.5 type 'number' includes 0-9, '*', '#'Writing corrected: “Softkey:BackSpace”, “Softkey:NextSpace”, “Softkey:ChangeMode”,

1.1 29.05.2013 1.1.48 4.1 Make screenshot using HTTP GET Device control URL

1.2 14.06.2013 1.1.62 3.1 Optional attribute “line” for Execute URI

1.2 21.06.2013 1.1.69 3.7 IPPhoneStatus: presentation of (maximum one) message on idle screen added

1.3 26.07.2013 3.5 Comments and example modified

1.3 05.08.2013 1.1.108 3.1, 3.3, 3.4, 3.6, 3.5, 3.14.3

Several XML UI objects: added attribute destroyOnExit IPPhoneExecute: added attribute triggerDestroyOnExit

1.3 07.08.2013 1.1.111 3.7 IPPhoneStatus:added attribute triggerDestroyOnExit

1.3 16.08.2013 1.1.118 2.6.3 New internal URI Command:Resync for XML Execute object

1.3 19.08.2013 1.1.120 3.3, 3.6 SoftKey “Edit_and_Dial” added in IPPhoneTextMenu and IPPhoneDirectory

1.3 19.08.2013 1.1.120 3.3 IPPhoneTextMenu: Optional SIP line selection for dialing added.

1.3 26.08.2013 1.1.123 3.13.2,3.3, 3.4, 3.6,

Hard keys 0-9, *. # can be setup with URLs. IPPhoneTextMenu, IPPhoneDirectory, IPPhoneTextScreen

2.0 26.09.2013 1.2.25 3.12, 4.2 XmlDeviceInfo Service URL

2.0

2.0 10.10.2013 2.0.65 2.4.1 Runtime URL-Variable {filter} added

2.0 10.10.2013 2.0.65 3.8, 3.9, 3.13.3

New: IPPhoneText and IPPhoneDirectory (Type B)

2.0 11.10.2013 2.0.74 3.8, 3.9 Default soft keys added: IPPhoneText and IPPhoneDirectory (Type B)

2.0. 05.11.2013 2.0.74 2.1.3 External phone book services

2.1 15.11.2013 2.0.89 2.1.3, 2.4.1 Runtime URL-Variable {search_key} added

2.2 09.12.2013 2.0.114 2.6.2 New: internal LED URIs “Led:mute=” and “Led:speaker=”

2.3 02.10.2014 any 2.4 Corrections

2.4 13.10.2014 >= 3.0.0 2.6.2 New: internal LED URIs for selection keys

2.5 21.11.2014 >= 3.1.1 3.13.2, 3.13.3

Customization of hard keys enhanced for user interface (UI) XML objects.

2.6 09.12.2014 >= 3.1.1 3.9 Corrections

2.6 09.12.2014 >= 3.1.1 3.10 New: IPPhoneMenu

Page 46 / 50


Page 47 / 50


Tiptel.com GmbH Business SolutionsHalskestraße 1D - 40880 RatingenTel.: 0900 100 – 84 78 35* Vanity Tel.: 0900 100 – TIPTEL* Internet: www.tiptel.deInternational:Internet: www.tiptel.com

Tiptel GmbHRicoweg 30/B1A - 2351 Wiener NeudorfTel.: 02236/677 464-0Fax: 02236/677 464-22E-mail: [email protected]: www.tiptel.at

Tiptel AGBahnstrasse 46CH - 8105 RegensdorfTel.: 044 - 843 13 13Fax: 044 - 843 13 23E-mail: [email protected]: www.tiptel-online.ch

Tiptel B.V.Camerastraat 2NL – 1322 BC AlmereTelefoon: 036 – 53 666 50Fax: 036 – 53 678 81E-mail: [email protected]: www.tiptel.nl

Tiptel NVLeuvensesteenweg 510 bus 4B – 1930 ZaventemTelefoon: 0903 99 333 (1,12 Euro / min.)Fax: 02 714 93 34E-mail: [email protected]: www.tiptel.be

Tiptel sarl23, avenue René Duguay-TrouinF – 78960 Voisins-Le-BretonneuxTél. : 01 / 39 44 63 30Fax : 01 / 30 57 00 29e-mail : [email protected] (en) 12/2014Internet : www.tiptel.fr

Page 48 / 50

*(1,49 Euro/Min. aus dem Festnetz der Deutschen Telekom, abweichende Mobilfunkpreise möglich)

Documents

XML API for SIP Phones 31xx