Grandstream Networks, Inc.

CTI Guide
 Table of Contents

SUPPORTED DEVICES ................................................................................................. 3

INTRODUCTION ............................................................................................................. 4

BENEFITS OF CTI .......................................................................................................... 5

ENABLING CTI FEATURE ............................................................................................. 6

CTI COMMANDS FORMAT DEFINITION ...................................................................... 7

Request format ......................................................................................................................................... 7
Response format ...................................................................................................................................... 7

TYPE OF CTI FUNCTIONS ............................................................................................ 8

CTI COMMANDS AND EXAMPLES............................................................................... 9

Functions used on GXP phones only ....................................................................................................... 9
Line Status Function ........................................................................................................................................9
Phone Status Function .....................................................................................................................................9
Phone Operations Functions..........................................................................................................................10
Functions used on DP750/720 only ....................................................................................................... 10
Account Status...............................................................................................................................................10
Handset Status ..............................................................................................................................................11
Handset Line Status .......................................................................................................................................11
Make Call .......................................................................................................................................................12
Device Operations Functions .........................................................................................................................12
Functions used on all Models ................................................................................................................. 13
Sending Keys Functions .................................................................................................................................13
System Operations Functions ........................................................................................................................16

Page | 2
CTI Guide
SUPPORTED DEVICES
Following table shows Grandstream products supporting CTI commands:

Model Supported Firmware

GXP16XX Series

GXP1610 Yes 1.0.3.28 or higher

GXP1620/1625 Yes 1.0.3.28 or higher

GXP1628 Yes 1.0.3.28 or higher

GXP1630 Yes 1.0.3.28 or higher

GXP17XX Series

GXP1760 Yes 1.0.0.37 or higher

GXP1780/1782 Yes 1.0.0.37 or higher

GXP21XX Series

GXP2130 Yes 1.0.7.25 or higher

GXP2140 Yes 1.0.7.25 or higher

GXP2160 Yes 1.0.7.25 or higher

GXP2135 Yes 1.0.7.25 or higher

GXP2170 Yes 1.0.7.25 or higher

DP750/720

DP750/720 Yes 1.0.4.2 or higher

Page | 3
CTI Guide
INTRODUCTION
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 DP750/720, GXP16XX, GXP17XX and GXP21XX 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.

Page | 4
CTI Guide
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.

Page | 5
CTI Guide
ENABLING CTI FEATURE
To enable CTI feature on GXP21xx series, follow steps below:

1. Access GXP21xx web GUI as administrator.

2. Navigate to Network → Remote Control.

3. Enable Action URI Support by checking “Enabled”.

4. On field Action URI Allowed IP List, put the remote party's IP address. If the IP address is
unknown, add "any".

5. Set Remote Control Pop up Window Support to “Disabled” to allow remote control without
confirmation on the physical phone.

6. Press Save and Apply button.

Note: The CTI feature is enabled by default on DP750/720, GXP17xx and GXP16xx phones.

Page | 6
CTI Guide
CTI COMMANDS FORMAT DEFINITION

Request format
The general CTI commands request format is:
http://Phone-IP-Address/cgi-bin/function?passcode=PASSWORD&param=value

“Function” is one of CTI functions as described in next chapter (api-get_line_status for example)
“Password” is the phone’s admin 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}]}

Page | 7
CTI Guide
TYPE OF CTI FUNCTIONS
Please refer to following table describing type of CTI functions supported:

Type Function Description

Functions used on GXP phones only

Line Status api-get_line_status Retrieves line status of the phone

Phone Status api-get_phone_status Retrieves phone status

Sends phone operations commands (hang up, answer

Phone Operations api-phone_operation
call, reject call…)

Functions used only on DP750/720

Account Status api-get_account_status Retrieves account status

Handset Status api-get_hs_status Retrieves handset status

Handset Line
api-get_hs_line_status Retrieves handset line status
Status

Make Call api-make_call Make a call using a specific handset

Sends device operations commands: mute, speaker,

api-device_operation
Device Operations setdnd…

Functions used on all models

Sends keys functions (speaker, volume up, volume

Send Keys api-send_key
down, mute, hold, 0-9… )

System
api-sys_operation Sends system operations commands (reset, reboot…)
Operations

Page | 8
CTI Guide
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 GXP2135 phone is used with IP address 192.168.5.135 and admin level password set
to default (passcode=admin).

Functions used on GXP phones only

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":"success", "body": [{"line": 1, "state": "idle",

"acct": "", "remotename": "", "remotenumber": "", "active":
Response 0}, {"line": 2, "state": "idle", "acct": "", "remotename": "",
"remotenumber": "", "active": 0}, {"line": 3, "state": "idle",
"acct": "", "remotename": "", "remotenumber": "", "active":
0}]}

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

Phone available
{"response":"success", "body": "available", "misc": "0"}
Response
Phone busy
{"response":"success", "body": "busy", "misc": "0"}

Page | 9
CTI Guide
 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

End established http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=endcall
endcall
call

Put the http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=holdcall

established call
holdcall on Hold

Accept incoming http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=acceptcall

acceptcall
call

Reject incoming http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=rejectcall

rejectcall
call

Reject or cancel http://192.168.5.135/cgi-bin/api-phone_operation?passcode=admin&cmd=cancel

cancel
calls

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}

Functions used on DP750/720 only

Account Status

General Format
The general format of CTI command to retrieve account status is:
http://Phone-IP-Address/cgi-bin/api-get_account_status?passcode=PASSWORD&account=NUMBER

P a g e | 10
CTI Guide
Example

Request http://192.168.5.135/cgi-bin/api-get_account_status?passcode=admin&account=1

Registered
{ "response": "success", "Account1": { "Registered": 1,
"Profile": 1, "Active": 1, "HSMode": "HS1" } }
Response
Not registered
{ "response": "success", "Account1": { "Registered": 0,
"Profile": 1, "Active": 0, "HSMode": "HS1" } }

Handset Status

General Format
The general format of CTI command to retrieve handset status is:
http://Phone-IP-Address/cgi-bin/api-get_hs_status?passcode=PASSWORD&hs=NUMBER

Example

Request http://192.168.5.135/cgi-bin/api-get_hs_status?passcode=admin&hs=1

Handset paired
{ "response": "success", "HS1": { "initialized": 1,
"subscribed": 1, "status": "idle" } }
Response
Handset not paired
{ "response": "success", "HS1": { "initialized": 0,
"subscribed": 0, "status": "" } }

Handset Line Status

General Format
The general format of CTI command to retrieve handset line status is:
http://Phone-IP-Address/cgi-bin/api-get_hs_line_status?passcode=PASSWORD&hs=NUMBER

Example

Request http://192.168.5.135/cgi-bin/api-get_hs_line_status?passcode=admin&hs=1

{ "response": "success", "HS1": { "Line1": { "Status": "idle",

"Account": 1, "Registered": 1, "Active": 1 }, "Line2": {
"Status": "idle", "Account": 0, "Registered": 0, "Active": 0
}, "Line3": { "Status": "idle", "Account": 0, "Registered": 0,
Response "Active": 0 }, "Line4": { "Status": "idle", "Account": 0,
"Registered": 0, "Active": 0 }, "Line5": { "Status": "idle",
"Account": 0, "Registered": 0, "Active": 0 }, "Line6": {
"Status": "idle", "Account": 0, "Registered": 0, "Active": 0
}, "Line7": { "Status": "idle", "Account": 0, "Registered": 0,

P a g e | 11
CTI Guide
 "Active": 0 }, "Line8": { "Status": "idle", "Account": 0,
"Registered": 0, "Active": 0 }, "Line9": { "Status": "idle",
"Account": 0, "Registered": 0, "Active": 0 }, "Line10": {
"Status": "idle", "Account": 0, "Registered": 0, "Active": 0 }
} }

Make Call

General Format
The general format of CTI command to initiate call is:
http://Phone-IP-Address/cgi-bin/api-
make_call?passcode=PASSWORD&hs=NUMBER&phonenumber=NUMBERS

Example

Request http://192.168.5.135/cgi-bin/api-make_call?passcode=admin&hs=1&phonenumber=3501

Response { "response": "success", "body": true }

Device Operations Functions

General Format
The general format of CTI command to send device operations is:
http://Phone-IP-Address/cgi-bin/api-
device_operation?passcode=PASSWORD&hs=NUMBER&line=NUMBER&cmd=OPERATION

Examples

Operation Function Examples

End http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&line=1&cmd=endcall
endcall
established
call

Put the http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&line=1&cmd=holdcall

holdcall established
call on
Hold

Resume http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&line=1&cmd=unholdcall
unholdcall
on-hold call

P a g e | 12
CTI Guide
 Accept
acceptcall incoming http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&line=1&cmd=acceptcall
call

Reject
rejectcall incoming http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&line=1&cmd=rejectcall
call

Reject or
cancel
cancel calls http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&line=1&cmd=cancel

For mute, speaker, setdnd and unsetdnd commands, there is no “line=x” argument

Mute while
mute
on call http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&cmd=mute

Enable
speaker http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&cmd=speaker
speaker
while on
call

Enable
setdnd http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&cmd=setdnd
DND

Disable
unsetdnd http://192.168.5.135/cgi-bin/api-device_operation?passcode=admin&hs=1&cmd=unsetdnd
DND

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}

Functions used on all Models

Sending Keys Functions

General format

• For GXP Series

The general format of CTI command to send keys functions is:

http://Phone-IP-Address/cgi-bin/api-send_key?passcode=PASSWORD&keys=KEY

P a g e | 13
CTI Guide
 • For DP750/720

The general format of CTI command to send keys functions is:

http://Phone-IP-Address/cgi-bin/api-send_key?passcode=PASSWORD&hs=NUMBER&keys=KEY

Examples

Key Function Example

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SPEAKER
Enable or
SPEAKER
Disable Speaker
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=SPEAKER

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=XFER
XFER Enable Transfer
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

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=MUTE
Enable / Disable
MUTE
Mute
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=MUTE

Put the call on http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=HOLD

HOLD
Hold
Note: This command works only during established call

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=1:0:0:0
Note: The phone will send number 1000
Send standard
0-9,*,#
keypad keys
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=1:0:0:0:HASH
Note: # key need be sent as HASH on DP750/DP720

Select phone
LINE[1-8] http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=LINE1
line

Enable
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=CONF
CONF conference
mode Note: This command works only during established call

Access to Voice
VM http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=VM
mail

Enable Headset
HEADSET http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=HEADSET
Mode

P a g e | 14
CTI Guide
 Enable / Disable
DND http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=DND
DND mode

SEND Send call http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SEND

SOFT[1-4] Select soft keys http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SOFT1

Select MPK http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=MPK1

MPK[1-24]
keys

LEFT_SOF Press left soft

T_KEY key http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=LEFT_SOFT_KEY

RIGHT_SO Press right soft

FT_KEY key http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=RIGHT_SOFT_KEY

STAR Press star key http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=STAR

ONHOOK Reject call http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=ONHOOK
OFFHOOK Answer call
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=OFFHOOK
OK Press OK http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=OK
LOCK Lock keypad http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=LOCK
UNLOCK Unlock keypad
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=UNLOCK
UP Press UP http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=UP
DOWN Press DOWN http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=DOWN
LEFT Press LEFT
http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=LEFT
RIGHT Press RIGHT http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&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"}

P a g e | 15
CTI Guide
 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 http://192.168.5.135/cgi-bin/api-sys_operation?passcode=admin&request=REBOOT
the phone

Reset the
phone to http://192.168.5.135/cgi-bin/api-sys_operation?passcode=admin&request=RESET
RESET
default
settings

Positive answer
If accepted, the command will be run instantly on the phone and below positive answer can be returned:

Reboot (all models except DP750): {"response":"success", "body": "savereboot"}

Reboot (DP750): {"response":"success", "body": "directreboot"}

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"}

P a g e | 16
CTI Guide