Skip to main content
Skip table of contents

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 VersionSIP Js Version
4.5.1V3.1.1_b-CIM-15311

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

Commands Sample


Sample

Sample

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

Sample

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

Sample

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

Sample

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

Sample

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


  1. dialogState(DROPPED)
5holdCallThis command allows a user to hold a call

Sample

JS 
{
				"action": "holdCall",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback
				}
			};
  1. dialogState(HELD)
6retrieveCallThis command allows a user to Resume a call. 

Sample

JS 
{
				"action": "retrieveCall",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback
				}
			};
  1. dialogState(ACTIVE)
7logoutThis command will logout the agent from the CTI

Sample

JS 
{
				"action": "logout",
				"parameter":
				{
					"reasonCode": "Logged Out",
					"userId": "448899",
					"clientCallbackFunction": eventCallback
				}
			};
  1. agentState
8muteThis command will mute the call from agent side. 
type : 'audio' / 'video'
JS 
{
				"action": "mute_call",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback,
					"type" : type
				}
			}
  1. dialogState(participants.mute = true)


9unmute

This command will unmute the call from agent side. 

type : 'audio' / 'video'

JS 
{
				"action": "unmute_call",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback,
					"type" : type
				}
			}
  1. dialogState(participants.mute = false)


10SST (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.
JS 
{
				"action": "SST",
				"parameter":
				{
					"dialogId": "0334343",
					"numberToTransfer":"99887766",
					"clientCallbackFunction": eventCallback
				}
			}

Agent A

  1. dialogState(DROPPED)


Agent B

  1. newInboundCall


11SST_Queue(Blind transfer on queue)This command allows a user to transfer the call  on queue blindly.
JS 
{
				"action": "SST_Queue",
				"parameter":
				{
					"dialogId": "0334343",					"queue":"queue_name",
"queueType ":"queueType ",      "clientCallbackFunction": eventCallback
				}
			}

Agent A

  1. dialogState(DROPPED)


Agent B

  1. newInboundCall
12SendDtmf

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


Here message  is the dtmf that we need to send.  

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

Event for  CTI

1agentInfo

 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

Sample

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

Sample

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

Sample

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

Sample

JS 
{
    "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
                }
            ]
        }
    }
}
4outboundDialingThis event will trigger when the user starts the outbound Dialing

Sample 

Sample

JS 
{
    "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
                }
            ]
        }
    }
}
5consultCall 

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

Sample

JS 
{
    "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
                }
            ]
        }
    }
}
6RONA

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. 




JS 
{
    "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"
        }
    }
}
7xmppEventThis event will be triggered when network connection status changes i.e it will be triggered when network status is connected or disconnected.
JS 
{
    "event" : "xmppEvent",
    "response" :
    {
        "loginId" : username,
        "type" : "IN_SERVICE",
        "description":"connected",
    }
}

types:

OUT_OF_SERVICE

IN_SERVICE

8DTMFThis event will be triggered when we send DTMF during IVR playing. 
JS 
{
                    "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
1subscriptionFailedThis error occurs when JS API  tries to get a subscription of an agent with supplied credentials and those credentials are invalid.

Sample 

Sample

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

Sample

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

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

Sample

JS 
{
    "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 NoParameterDetails
1callType

calltypes ={

inboundType : "OTHER_IN",

outboundType : "OUT",

}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close