How it Works
TIPTEL
Loading...
31xx
User Manual
49 pgs771.34 Kb0

TIPTEL 31xx User Manual

XML API Guide (en)
Version 2.6
tiptel 31xx
tiptel
XML API for Tiptel.com SIP Phones 31xx
Last changes: 09.12.2014
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
XML API for Tiptel.com SIP Phones 31xx
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 tables
Table 1: Customizable hard keys in object “SoftKey”..............................................................................................39
Table 2: Customizable hard keys in object “SoftKeyItem”.......................................................................................40
1 Abbreviations
API Application Programming Interface SIP Session Initiation Protocol UI User Interface URL Uniform Resource Locator, in this document the same as URI URI Uniform Resource Identifier RFCs 1630, 3986 XML eXtensible Markup Language
Page 2 / 50
XML API for Tiptel.com SIP Phones 31xx
2 XML Services
The 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 service
The 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
XML API for Tiptel.com SIP Phones 31xx
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 service
In 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 file
minibrowserurl=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.xml
Please 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
XML API for Tiptel.com SIP Phones 31xx
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:3030@192.168.1.103:5060 SIP/2.0 Via: SIP/2.0/UDP 192.168.1.101:5060;branch=ad5jh4ut9dsnf3jtf;rport From: <sip:3020@192.168.1.101:5060>;tag=54dg7853c4 To: 3030 <sip:3030@192.168.1.103:5060> Contact: <sip:3020@192.168.1.101> Call-ID: 65835h8s46f2x429 CSeq: 20 NOTIFY Max-Forwards: 1 Event: tiptel-actionurl Content-Type: text/plain Content-Length: 37
http://192.168.1.1/myfiles/mymenu_{mac}.xml
XML API for Tiptel.com SIP Phones 31xx
2.3 XML Format
The 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:3020@192.168.1.101:5060 SIP/2.0 Via: SIP/2.0/UDP 192.168.1.101:5060;branch=ad5jh4ut9dsnf3jtf;rport From: <sip:3020@192.168.1.101:5060>;tag=54dg7853c4 To: 3030 <sip:200@10.30.100.103:5060> Contact: <sip:3020@192.168.1.101> Call-ID: 65835h8s46f2x429 CSeq: 20 NOTIFY Event: tiptel-xml Content-Type: application/xml Content-Length: 140
<?xml version="1.0" encoding="UTF-8"?> <TiptelIPPhoneExecute Beep="yes"> <ExecuteItem URI="Led:BACKLIGHT=on"/> </TiptelIPPhoneExecute>
XML API for Tiptel.com SIP Phones 31xx
tftp://xxxx/yyy/file.xml ftp://xxxx/yyy/file.xml http://xxxx/yyy/file.cgi?querykey=queryvar https://xxxx/yyy/file.php?querykey=queryvar sip:xxxx tel: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 phonebook
Example: 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
XML API for Tiptel.com SIP Phones 31xx
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>
XML API for Tiptel.com SIP Phones 31xx
– 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
fkeyNN fkeyNN.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:fkey5 Key:fkey5.0
fkeyNN.M Emulate the key of on an extension module
NN 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-9
N 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 button
N is the alpha character
Key:alpha_A Key: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
XML API for Tiptel.com SIP Phones 31xx
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_CCC fkeyNN.0_CCC
Controls the LEDs of phone function keys
NN 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=fastflash Led:fkey5.0_red=fastflash Led:fkey8=off Led:fkey8.0=off Led:fkey8.0_green=off
fkeyNN.s_CCC Supported since Firmware 3.0.0. on phones with colour displays
Controls 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=fastflash Led:fkey2.s_green=slowflash Led:fkey3.s_green=on Led:fkey3.s_red=off Led:fkey3.s=off
fkeyNN.M_CCC Controls the LEDs of an extension module
NN 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=fastflash Led:fkey6.1_green=slowflash Led:fkey7.1_green=on Led:fkey8.1_red=off Led: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"/> <!-- LED icon of first selection key on display --> <ExecuteItem URI="Led:fkey1.s_amber=fastflash"/> </TiptelIPPhoneExecute>
<?xml version="1.0" ?> <TiptelIPPhoneExecute> <ExecuteItem URI="Key:fkey2"/> <ExecuteItem URI="Key:line3"/> </TiptelIPPhoneExecute>
XML API for Tiptel.com SIP Phones 31xx
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 reboot
The 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>
XML API for Tiptel.com SIP Phones 31xx
➢ "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 IPPhoneInputScreenIPPhoneDirectory
(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
XML API for Tiptel.com SIP Phones 31xx
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 object
The 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>
XML API for Tiptel.com SIP Phones 31xx
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 object
Not yet implemented.
3.3 IPPhoneTextMenu XML object
The IPPhoneTextMenu XML object can be used to display a non-formatted menu.
XML file description:
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>
Loading...
+ 34 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use