Breadcrumbs

FreeSWITCH JS API (v3.1.1)


This library of SIP.js can be used either as a standalone implementation or with EFCX.


Please refer to the table below for compatible EFCX versions

EFCX Version

SIP Js Version

4.5.1

V3.1.1_b-CIM-15311

To send commands, you need to import the following libraries FreeSwitch

Commands Sample


Sample

JavaScript
{
				"action": "login",
				"parameter":
				{
					"loginId": "jazeb",
					"password": "1234",
					"extension": "448899",
					"clientCallbackFunction": eventCallback
				}
			};

Commands for CTI


Story

Description

Commands

Events

1

login

The Login command is used to actually Register an agent associated extension and log in to CTI. Login command parameters are

  • Agent Login ID (Agent Name)

  • Password (Extenstion password and Agent password must be same)

  • extension 

First JS API will  register extension to webphone, If Registeration got failed, the following event will be thrown 

Following errors are possible:

  1. subscriptionFailed

  2. networkIssue

If a Registeration is successful, will send the following event. agentState and dialogState events. Now the agent will be able to make and receive calls on the client application.

Sample 

JavaScript
{
				"action": "login",
				"parameter":
				{
					"loginId": "jazeb",
					"password": "1234",
					"extension": "448899",
					"clientCallbackFunction": eventCallback
				}
			};


Successful Events : 

  1. agentInfo

  2. dialogState

Failure Events :

  1. subscriptionFailed

  2. invalidState

2

makeCall

This command allows a user to make a call. To make a call, a new Dialog object is created that specifies the <Extension_Number> (the destination target). The new Dialog object is posted to the Dialog collection for that user. 

Here callType parameter value would be audio/video

Sample 

JavaScript
{
"action": "makeCall",
"parameter":
{
"callType" : "audio",
"Destination_Number":"1777",
"calledNumber": "1777",
"clientCallbackFunction": eventCallback
}
}


  1. outboundDialing(INITIATING, INITIATED)

  2. dialogState (ACTIVE)

3

answerCall

This command allows a user to answer a call. 

Sample 

JavaScript
{
				"action": "answerCall",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback
				}
			};


  1. dialogState(ACTIVE)

4

releaseCall

This command allows a user to drop a call. 

Sample

JavaScript
{
	"action" 	: "releaseCall",
	"parameter"	:
		{
      "dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf"
		}
};


  1. dialogState(DROPPED)

5

holdCall

This command allows a user to hold a call


JavaScript
{
				"action": "holdCall",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback
				}
			};


  1. dialogState(HELD)

6

retrieveCall

This command allows a user to Resume a call. 


JavaScript
{
				"action": "retrieveCall",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback
				}
			};


  1. dialogState(ACTIVE)

7

logout

This command will logout the agent from the CTI


JavaScript
{
				"action": "logout",
				"parameter":
				{
					"reasonCode": "Logged Out",
					"userId": "448899",
					"clientCallbackFunction": eventCallback
				}
			};


  1. agentState

8

mute

This command will mute the call from agent side. 
type : 'audio' / 'video'


JavaScript
{
				"action": "mute_call",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback,
					"type" : type
				}
			}


  1. dialogState(participants.mute = true)

9

unmute

This command will unmute the call from agent side. 

type : 'audio' / 'video'


JavaScript
{
				"action": "unmute_call",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback,
					"type" : type
				}
			}


  1. dialogState(participants.mute = false)

10

SST (blind transfer)

This command allows a user to transfer the call  on agent extension blindly without waiting for the other agent to receive the call.


JavaScript
{
				"action": "SST",
				"parameter":
				{
					"dialogId": "0334343",
					"numberToTransfer":"99887766",
					"clientCallbackFunction": eventCallback
				}
			}


Agent A

  1. dialogState(DROPPED)


Agent B

  1. newInboundCall

11

SST_Queue(Blind transfer on queue)

This command allows a user to transfer the call  on queue blindly.


JavaScript
{
				"action": "SST_Queue",
				"parameter":
				{
					"dialogId": "0334343",					"queue":"queue_name",
"queueType ":"queueType ",      "clientCallbackFunction": eventCallback
				}
			}


Agent A

  1. dialogState(DROPPED)


Agent B

  1. newInboundCall

12

SendDtmf

This command allows user to send dtmf during the IVR playing.


Here message  is the dtmf that we need to send.  


JavaScript
postMessages({
"action": "SendDtmf",
"parameter":
{
"dialogId": dialogid,
"message":"1",
"clientCallbackFunction": eventCallback
}
});


  1. DTMF

Event for  CTI

1

agentInfo

 JS API sends this event when the device logged in successfully with state LOGIN. This event will never be sent again in a session

Sample

JavaScript
{
    "event": "agentInfo",
    "response": {
        "loginId": "448899",
        "extension": "448899",
        "state": "LOGIN",
        "cause": "null"
    }
}


JavaScript
{
    "event": "agentInfo",
    "response": {
        "loginId": "448899",
        "extension": "448899",
        "state": "LOGOUT",
        "cause": "Connection Error"
    }
};

Possible value for state

  • LOGIN

  • LOGOUT

2

dialogState

 Dialog state event represents the current state of the dialog.


Use both dialog's state and participant's state provided in response JSON object to figure out call state.


Sample 

JavaScript
{
    "event": "dialogState",
    "response": {
        "loginId": "448899",
        "dialog": {
            "id": "0lsns4ou3n9bi7erg9lq",
            "fromAddress": "448899",
            "dialedNumber": "448866",
            "customerNumber": "448866",
            "dnis": null,
            "serviceIdentifer" : null,
            "callType": "OUT",
            "ani": "448866",
            "wrapUpReason": null,
            "callEndReason": null,
            "queueName": null,
            "associatedDialogUri": null,
            "secondaryId": null,
            "participants": [
                {
                    "actions": {
                        "action": [
                            "TRANSFER_SST",
                            "HOLD",
                            "SEND_DTMF",
                            "DROP"
                        ]
                    },
                    "mediaAddress": null,
                    "mediaAddressType": "SIP.js/0.15.11-CTI/Expertflow",
                    "startTime": "2023-06-20T08:51:35.993Z",
                    "state": "ACTIVE",
                    "stateCause": null,
                    "stateChangeTime": "2023-06-20T08:51:38.022Z",
                    "mute": false
                }
            ],
            "callVariables": {
                "CallVariable": [
                    {
                        "name": "callVariable0",
                        "value": ""
                    }
                ]
            },
            "state": "ACTIVE",
            "isCallAlreadyActive": false,
            "callbackNumber": null,
            "outboundClassification": null,
            "scheduledCallbackInfo": null,
            "isCallEnded": 0,
            "eventType": "PUT"
        }
    }
}

The current state of the dialog. Possible values are:

  • INITIATING

  • INITIATED

  • ALERTING

  • ACTIVE

  • FAILED

  • DROPPED

  • ACCEPTED

3

newInboundCall

This event occurs when an incoming call is ringing for the agent. This event specifies from address, call variables, and dialog id for the agent. The client needs to activate the control for accepting or rejecting the call. 

Sample

JavaScript
{
    "event": "newInboundCall",
    "response": {
        "loginId": "448899",
        "dialog": {
            "id": "b86fc00f2a094f3c85ca53ec71d18ab4",
            "ani": "448866",
            "customerNumber": "448866",
            "associatedDialogUri": null,
            "callbackNumber": null,
            "outboundClassification": null,
            "scheduledCallbackInfo": null,
            "isCallEnded": 0,
            "eventType": "PUT",
            "callType": "OTHER_IN",
            "queueName": null,
            "dialedNumber": "448899",
            "dnis": "448899",
            "serviceIdentifer" : 448899,
            "secondaryId": null,
            "state": "ALERTING",
            "isCallAlreadyActive": false,
            "wrapUpReason": null,
            "callEndReason": null,
            "fromAddress": "448866",
            "callVariables": {
                "CallVariable": [
                    {
                        "name": "callVariable0",
                        "value": "d822cc8c-c19a-4a19-88c5-7b159f33331f"
                    },
                    {
                        "name": "callVariable1",
                        "value": "ACD_IN"
                    }
                ]
            },
            "participants": [
                {
                    "actions": {
                        "action": [
                            "ANSWER"
                        ]
                    },
                    "mediaAddress": "448899",
                    "mediaAddressType": "SIP.js/0.15.11-CTI/Expertflow",
                    "startTime": "2023-06-20T09:55:54.120Z",
                    "state": "ALERTING",
                    "stateCause": null,
                    "stateChangeTime": "2023-06-20T09:55:54.120Z",
                    "mute": false
                }
            ]
        }
    }
}


4

outboundDialing

This event will trigger when the user starts the outbound Dialing

Sample 

JavaScript
{
    "event": "outboundDialing",
    "response": {
        "loginId": "448899",
        "dialog": {
            "id": "0lsns4ou3n9bi7erg9lq",
            "ani": "448866",
            "customerNumber": "448866",
            "associatedDialogUri": null,
            "callbackNumber": null,
            "outboundClassification": null,
            "scheduledCallbackInfo": null,
            "isCallEnded": 0,
            "eventType": "PUT",
            "callType": "OUT",
            "queueName": null,
            "dialedNumber": "448866",
            "dnis": "448866",
            "serviceIdentifer" : 448899,
            "secondaryId": null,
            "state": "INITIATING",
            "isCallAlreadyActive": false,
            "wrapUpReason": null,
            "callEndReason": null,
            "fromAddress": "448899",
            "callVariables": {
                "CallVariable": []
            },
            "participants": [
                {
                    "actions": {
                        "action": [
                            "TRANSFER_SST",
                            "HOLD",
                            "SEND_DTMF",
                            "DROP"
                        ]
                    },
                    "mediaAddress": "448899",
                    "mediaAddressType": "SIP.js/0.15.11-CTI/Expertflow",
                    "startTime": "2023-06-20T08:51:35.993Z",
                    "state": "INITIATING",
                    "stateCause": null,
                    "stateChangeTime": "2023-06-20T08:51:35.993Z",
                    "mute": false
                }
            ]
        }
    }
}


5

consultCall 

This event informs the client about the current state of consult call for an agent. 


The current state of the dialog. Possible values are:

  • INITIATING

  • INITIATED

  • ALERTING

  • ACTIVE

  • DROPPED


JavaScript
{
    "event": "ConsultCall",
    "response": {
        "loginId": "4488992",
        "dialog": {
            "id": "u309sa95fuql5ktnc67a",
            "ani": "4488993",
            "customerNumber": "4488993",
            "associatedDialogUri": null,
            "callbackNumber": null,
            "outboundClassification": null,
            "scheduledCallbackInfo": null,
            "isCallEnded": 0,
            "eventType": "PUT",
            "callType": "CONSULT",
            "queueName": null,
            "queueType": null,
            "dialedNumber": "4488992",
            "dnis": "4488992",
            "serviceIdentifer" : 448899,
            "secondaryId": null,
            "state": "ACTIVE",
            "isCallAlreadyActive": false,
            "wrapUpReason": null,
            "callEndReason": null,
            "fromAddress": "4488993",
            "callVariables": {
                "CallVariable": [
                    {
                        "name": "callVariable0",
                        "value": "2607ac66-b05a-4c35-847d-14271b98c04e"
                    }
                ]
            },
            "participants": [
                {
                    "actions": {
                        "action": [
                            "ANSWER"
                        ]
                    },
                    "mediaAddress": "4488992",
                    "mediaAddressType": "SIP.js/0.15.11-CTI/Expertflow",
                    "startTime": "2023-08-18T15:00:06.843Z",
                    "state": "ACTIVE",
                    "stateCause": null,
                    "stateChangeTime": "2023-08-18T15:00:30.185Z",
                    "mute": false
                }
            ]
        }
    }
}


6

RONA

The customer initiated the call and the call is ringing on the agent's side, the agent does not accept the call and alerting/ringing times out

The customer initiated the call and the call is ringing on the agent's side, and the customer ends the call.

In above both case the value of the key endCallReason would be Canceled in dialogState event. 


JavaScript
{
    "event": "dialogState",
    "response": {
        "loginId": "448899",
        "dialog": {
            "id": "2a8f41ba-579d-123c-c78a-005056bc90cf",
            "fromAddress": "448866",
            "dialedNumber": "258963",
            "serviceIdentifer" : 258963,
            "customerNumber": "448866",
            "dnis": "911",
            "callType": "OTHER_IN",
            "ani": "448866",
            "wrapUpReason": "Queue Call",
            "queueName": null,
            "associatedDialogUri": null,
            "secondaryId": null,
            "participants": {
                "Participant": [
                    {
                        "actions": {
                            "action": [
                                "TRANSFER_SST",
                                "HOLD",
                                "SEND_DTMF",
                                "DROP"
                            ]
                        },
                        "mediaAddress": "448899",
                        "mediaAddressType": "SIP.js/0.15.11-CTI/Expertflow",
                        "startTime": "2023-4-17 13:32:0",
                        "state": "DROPPED",
                        "stateCause": null,
                        "stateChangeTime": "2023-3-17 13:32:19",
                        "localstream": null,
                        "remotestream": null,
                        "mute": false
                    }
                ]
            },
            "callVariables": {
                "CallVariable": [
                    {
                        "name": "callVariable0",
                        "value": "507d8a23-71b2-43e0-919a-09d125fa51ab"
                    },
                    {
                        "name": "callVariable1",
                        "value": "Umer"
                    },
                    {
                        "name": "callVariable2",
                        "value": "Saeed"
                    },
                    {
                        "name": "callVariable3",
                        "value": "Model Town"
                    },
                    {
                        "name": "callVariable4",
                        "value": "08-December-2008"
                    },
                    {
                        "name": "callVariable5",
                        "value": "03401234567"
                    },
                    {
                        "name": "callVariable6",
                        "value": "Japan"
                    },
                    {
                        "name": "callVariable7",
                        "value": "80094"
                    },
                    {
                        "name": "callVariable8",
                        "value": "34618-8449511-7"
                    },
                    {
                        "name": "callVariable9",
                        "value": "Japanese"
                    },
                    {
                        "name": "callVariable10",
                        "value": "05145679"
                    }
                ]
            },
            "state": "Canceled",
            "callbackNumber": null,
            "outboundClassification": null,
            "scheduledCallbackInfo": null,
            "isCallEnded": 0,
            "eventType": "PUT"
        }
    }
}


7

xmppEvent

This event will be triggered when network connection status changes i.e it will be triggered when network status is connected or disconnected.


JavaScript
{
    "event" : "xmppEvent",
    "response" :
    {
        "loginId" : username,
        "type" : "IN_SERVICE",
        "description":"connected",
    }
}


types:

OUT_OF_SERVICE

IN_SERVICE

8

DTMF

This event will be triggered when we send DTMF during IVR playing. 


JavaScript
{
                    "event": "DTMF",
                    "response":
                    {
                        "loginId": loginid,
                        "type": 0,
                        "description": "Failure response ",
                    }
                }

type:

1 for success response

0 for failure response 

Error Event for  CTI


Error Event Types

Description

Events

1

subscriptionFailed

This error occurs when JS API  tries to get a subscription of an agent with supplied credentials and those credentials are invalid.

Sample 

JavaScript
{
	"event"		: "Error",
	"response"	: 
		{
"type":"subscriptionFailed",
 "loginId":"Malik 3",
 "description":"Invalid Username or Password"/"INVALID_DOMAIN"   }
};


2

generalError

We define its type as general error and its description will tell what is the root cause of this error.

Sample 

JavaScript
{
	"event"		: "Error",
	"response"	: 
		{
"type":"generalError",
 "loginId":"1234",
 "description":"XMPP Connection Failed"
		}
};

In some cases description can also be 

"description": "Sorry we are unable to process your request"

3

invalidState

The object is in the incorrect state for the request, Send the request again.


JavaScript
{
    "event": "Error",
    "response": {
        "type": "invalidState",
        "loginId": null,
        "description": "The object is in the incorrect state for the request makeCall",
        "event_time": "2023-5-13 3:22:51.778"
    }
};



SR No

Parameter

Details

1

callType

calltypes ={

inboundType : "OTHER_IN",

outboundType : "OUT",

}