CTI Guide

  • Updated on July 4, 2022

CTI (Computer-Telephony Integration) provides the 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 DP75X, 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 the interaction between the customer’s phone and desk computer or can be run using a web browser on the customer’s computer.

This CTI 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 call notifications on desk computers allow caller numbers to be screened against a database to collect or provide more information about the caller.
  • Initiate outbound calls from the computer directly with the possibility of automatic and pre-dial calls commonly used for telemarketing.
  • Increase productivity and improve customer service.

ENABLING CTI FEATURE

To enable the CTI feature on the GXP21xx series, follow the 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 the 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 the Save and Apply button.
A screenshot of a cell phone

Description generated with very high confidence

The CTI feature is enabled by default on DP75x, GXP17xx and GXP16xx phones.

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

TYPE OF CTI FUNCTIONS

Please refer to following table describing type of CTI functions supported:

TypeFunctionDescription

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

Phone Operations

api-phone_operation

Sends phone operations commands (hang up, answer 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 Status

api-get_hs_line_status

Retrieves handset line status

Make Call

api-make_call

Make a call using a specific handset

Device Operations

api-device_operation

Sends device operations commands: mute, speaker, setdnd…

Functions used on all models

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 a computer on the same phone’s network. In the examples below, a GXP2135 phone is used with IP address 192.168.5.135 and an 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

{“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}]}

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

OperationFunctionExamples

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} 

Functions used on DP750/720 only

Account Status

General Format

The general format of the CTI command to retrieve account status is:

http://Phone-IP-Address/cgi-bin/api-get_account_status?passcode=PASSWORD&account=NUMBER

Example

Request

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

Response

Registered { “response”: “success”, “Account1”: { “Registered”: 1, “Profile”: 1, “Active”: 1, “HSMode”: “HS1” } }


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

Response

Handset paired { “response”: “success”, “HS1”: { “initialized”: 1, “subscribed”: 1, “status”: “idle” } }


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

{ “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, “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, “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

OperationFunctionExamples

endcall

End established call

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

holdcall

Put the established call on Hold

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

unholdcall

Resume on-hold call

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

acceptcall

Accept incoming call

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

rejectcall

Reject incoming call

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

cancel

Reject or 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

Mute while on call

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

speaker

Enable speaker while on call

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

setdnd

Enable DND

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

unsetdnd

Disable DND

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

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
  • 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

KeyFunctionExample

SPEAKER

Enable or Disable Speaker

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&keys=SPEAKER

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&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

http://192.168.5.135/cgi-bin/api-send_key?passcode=admin&hs=1&keys=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
Note: The phone will send number 1000

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

LINE[1-8]

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=DND

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

MPK[1-24]

Select MPK keys

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

LEFT_SOFT_KEY

Press left soft key

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

RIGHT_SOFT_KEY

Press right soft 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"} 

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

OperationFunctionExample

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 (all models except DP75X):

{"response":"success", "body": "savereboot"}

Reboot (DP75X):

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

SUPPORTED DEVICES

The following table shows Grandstream products supporting CTI commands:

ModelSupportedFirmware

GXP16XX Series

Yes

1.0.3.28 or higher

GXP17XX Series

Yes

1.0.0.37 or higher

GXP21XX Series

Yes

1.0.7.25 or higher

DP75X Series

Yes

1.0.4.2 or higher

Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Comment

We use cookies in order to give you the best possible experience on our website. By continuing to use this site, you agree to our use of cookies.
Accept