CTI (Computer-Telephony Integration) provides ability to manage phone calls from a computer including basic call operations such as making and answering calls, and advanced call operations such as call forward, conference, call hold and more.
Grandstream GRP26XX series support CTI operations and commands providing complete control over phone calls from a desktop computer. CTI commands can be integrated with a 3rd party application to control interaction between customer’s phone and desk computer or can be run using a web browser on customer’s computer.
This guide describes available operations and commands with examples how-to run them from a web browser.
BENEFITS OF CTI
The major benefits of using Computer Telephony Integration (CTI) are the following:
- Complete control over calls (answer, hang-up, call on hold, manage “do not disturb”, call forward, conference, call transfer and etc…).
- Incoming calls notifications on desk computer allowing caller numbers to be screened against a database to collect or provide more information related to caller.
- Initiate outbound calls from computer directly with possibility of automatic and pre-dial calls commonly used for telemarketing.
- Increase productivity and improve customer service.
ENABLING CTI FEATURE
To enable CTI feature on GRP26XX series, follow steps below:
- Access GRP26XX web GUI as administrator.
- Navigate to Network 🡪 Remote Control (on GRP261x/GRP2624/GRP2634) or Network Settings 🡪 Advanced Settings 🡪 Remote Control (on GRP260x).
- Enable Action URI Support by checking “Enabled”.
- On field Action URI Allowed IP List, put the remote party’s IP address. If the IP address is unknown, add “any”.
- Set Remote Control Pop up Window Support to “Disabled” to allow remote control without confirmation on the physical phone.
- Press Save and Apply button.
The “Click-To-Dial Feature” should be enabled under Settings 🡪 Call Features (on GRP261x/GRP2624/GRP2634) or under Phone Settings 🡪 Call Settings (on GRP260x), to be able to run the “Make Call” Command.
CTI COMMANDS FORMAT DEFINITION
Request format
The general CTI commands request format is:
http://Phone-IP-Address/cgi-bin/function?passcode=PASSWORD¶m=value
“Function” is one of CTI functions as described in next chapter (api-get_line_status for example)
“Password” is the phone’s admin/user level password
“Param=value” is the parameter for specific CTI function type
Response format
Positive answer with no returned value |
{“response”:”success”, “body”: “complete”} |
Negative answer |
{“response”:”error”, “body”: “failed”} |
Positive answer with returned values |
{“response”:”success”, “body”: [{“line”: 1, “state”: “idle”, “acct”: “”, “remotename”: “”, “remotenumber”: “”, “active”: 0}, {“line”: 2, “state”: “idle”, “acct”: “”, “remotename”: “”, “remotenumber”: “”, “active”: 0}, {“line”: 3, “state”: “idle”, “acct”: “”, “remotename”: “”, “remotenumber”: “”, “active”: 0}]} |
TYPE OF CTI FUNCTIONS
Please refer to following table describing type of CTI functions supported:
| Type | Function | Description |
|---|---|---|
Line Status | api-get_line_status | Retrieves line status of the phone |
Phone Status | api-get_phone_status | Retrieves phone status |
Phone Operations | api-phone_operation | Sends phone operations commands (hang up, answer call, reject call…) |
Send Keys | api-send_key | Sends keys functions (speaker, volume up, volume down, mute, hold, 0-9… ) |
System Operations | api-sys_operation | Sends system operations commands (reset, reboot…) |
CTI COMMANDS AND EXAMPLES
Following commands have been run in a web browser on computer in same phone’s network. In the examples below, a GRP26XX phone is used with IP address 192.168.5.135 and admin/user level password set to (passcode=admin).
As for the System operation
Functions used on GRP26XX
Line Status Function
General Format
The general format of CTI command to retrieve the line status is:
http://Phone-IP-Address/cgi-bin/api-get_line_status?passcode=PASSWORD
Example
Request | http://192.168.5.135/cgi-bin/api-get_line_status?passcode=admin |
Response | { "response": "success", "body": [ { "line": 1, "state": "idle", "acct": 0, "active": 0, "remotename": "", "remotenumber": "" }, { "line": 2, "state": "idle", "acct": 0, "active": 0, "remotename": "", "remotenumber": "" }, { "line": 3, "state": "idle", "acct": 0, "active": 0, "remotename": "", "remotenumber": "" }, { "line": 4, "state": "idle", "acct": 0, "active": 0, "remotename": "", "remotenumber": "" } ] } |
In this example, the phone shows that only one account is available on line 1; other lines are not registered.
Phone Status Function
General Format
The general format of CTI command to retrieve phone status is:
http://Phone-IP-Address/cgi-bin/api-get_phone_status?passcode=PASSWORD
Example
Request | http://192.168.5.135/cgi-bin/api-get_phone_status?passcode=admin |
Response | Phone available {“response”:”success”, “body”: “available”, “misc”: “0”} Phone busy {“response”:”success”, “body”: “busy”, “misc”: “0”} |
Phone Operations Functions
General format
The general format of CTI command to send phone operations is:
http://Phone-IP-Address/cgi-bin/api-phone_operation?passcode=PASSWORD&cmd=OPERATION
Examples
| Operation | Function | Examples |
|---|---|---|
endcall | End established call | http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=endcall |
holdcall | Put the established call on Hold | http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=holdcall |
acceptcall | Accept incoming call | http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=acceptcall |
rejectcall | Reject incoming call | http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=rejectcall |
cancel | Reject or cancel calls | http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=cancel |
Positive answer
If accepted, the command will be run instantly on the phone and below positive answer can be returned:
{“response”: “success”, “body”: true}
Negative answer
If not accepted, the phone will not react to it and below negative answer can be returned:
{“response”: “error”, “body”: false}
Make Call
General format
The general format of CTI command to initiate a call is:
http://Phone-IP-Address/cgi-bin/api-make_call?passcode=PASSWORD&phonenumber=NUMBER
Example
Request | http://192.168.5.135/cgi-bin/api-make_call?passcode=admin&phonenumber=3501 |
Response | { “response”: “success”, “body”: true } |
System Operations Functions
General Format
The general CTI command to send phone system operations is:
http://Phone-IP-Address/cgi-bin/api-sys_operation?passcode=PASSWORD&request=OPERATION
Examples
| Operation | Function | Example |
|---|---|---|
REBOOT | Reboot the phone | http://192.168.5.135/cgi-bin/api-sys_operation?passcode=admin&request=REBOOT |
RESET | Reset the phone to default settings | http://192.168.5.135/cgi-bin/api-sys_operation?passcode=admin&request=RESET |
Positive answer
If accepted, the command will be run instantly on the phone and below positive answer can be returned:
Reboot: {“response”:”success”, “body”: “savereboot”}
Reset: {“response”:”success”, “body”: “reset”}
Negative answer
If not accepted, the phone will not react to it and below negative answer can be returned:
{“response”:”error”, “body”: “unknown”}
The Reset Command requires the Admin level password in the passcode field.
Sending Keys Functions
General format
The general format of CTI command to send keys functions is:
http://Phone-IP-Address/cgi-bin/api-send_key?passcode=PASSWORD&keys=KEY
Examples
| Key | Function | Examples |
|---|---|---|
SPEAKER | Enable or Disable Speaker | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SPEAKER |
XFER | Enable Transfer | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=XFER Note: This command works only during established call |
VUP | Volume UP | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=VUP |
VDOWN | Volume Down | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=VDOWN |
MUTE | Enable / Disable Mute | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=MUTE Note: For this to work please set the “Mute Key Functions while idle” under Phone settings => Call Settings => General to Idle Mute. |
HOLD | Put the call on Hold | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=HOLD Note: This command works only during established call |
0-9,*,# | Send standard keypad keys | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=1:0:0:0 |
LINE[1-X] | Select phone line | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=LINE1 |
CONF | Enable conference mode | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=CONF Note: This command works only during established call |
VM | Access to Voice mail | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=VM |
HEADSET | Enable Headset Mode | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=HEADSET |
DND | Enable / Disable DND mode | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=MUTE Note: For this to work please set the “Mute Key Functions while idle” under Phone settings => Call Settings => General to DND. |
SEND | Send call | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SEND |
SOFT[1-X] | Select soft keys | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SOFT1 |
MPK[1-X] | Select MPK keys | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=MPK1 |
STAR | Press star key | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&&keys=STAR |
ONHOOK | Reject call | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=ONHOOK |
OFFHOOK | Answer call | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=OFFHOOK |
OK | Press OK | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&&keys=OK |
LOCK | Lock keypad | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=LOCK |
UNLOCK | Unlock keypad | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=UNLOCK |
UP | Press UP | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=UP |
DOWN | Press DOWN | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=DOWN |
LEFT | Press LEFT | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=LEFT |
RIGHT | Press RIGHT | http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=RIGHT |
Positive answer
If accepted, the command will be run instantly on the phone and below positive answer can be returned:
{“response”:”success”, “body”: “complete”}
Negative answer
If not accepted, the phone will not react to it and below negative answer can be returned:
{“response”:”error”, “body”: “unknown”}
SUPPORTED DEVICES
Following table shows Grandstream products supporting CTI commands:
| Model | Supported | Firmware |
|---|---|---|
GRP2612/GRP2612W/GRP2612P | Yes | 1.0.5.67+ |
GRP2613 | Yes | 1.0.5.67+ |
GRP2614 | Yes | 1.0.5.67+ |
GRP2615 | Yes | 1.0.5.67+ |
GRP2616 | Yes | 1.0.5.67+ |
GRP2624 | Yes | 1.0.5.67+ |
GRP2634 | Yes | 1.0.5.67+ |
GRP2601/P | Yes | 1.0.3.18+ |
GRP2602/P/W | Yes | 1.0.3.18+ |
GRP2603/P | Yes | 1.0.3.18+ |
GRP2604/P | Yes | 1.0.3.18+ |
