CTI Guide

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.

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

TYPE OF CTI FUNCTIONS

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

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

In this example, the phone shows that line 1 is in a call; the other lines are not in a call.

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

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

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} 

Account Status Function

General Format

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

http://phone-ip-address/cgi-bin/api-get_accounts?passcode=PASSWORD

Example

In this example, the phone shows account 1’s basic SIP information and that account 1 is registered.

Functions used on DP75x/720/722/730 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

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

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

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

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

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/722/730

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

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

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:

---