Skip to main content
Skip table of contents

FreeSWITCH JS API (v3.2.8)


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.23.2.8_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/screenshare

Sample 

Sample

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


  1. outboundDialing(INITIATING, INITIATED)
  2. dialogState (ACTIVE)
3makeOBCall

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

Here callType parameter value would be audio

Sample

Sample

JS 
{
"action": "makeOBCall",
"parameter":
{
"callType" : "audio",
"Destination_Number":"1777",
"calledNumber": "1777",
"clientCallbackFunction": eventCallback
}
}
  1. outboundDialing(INITIATING, INITIATED)
  2. dialogState (ACTIVE)
4

answerCall

This command allows a user to answer a call. 

Here answerCalltype parameter value would be audio/video/screenshare/onlyviewscreenshare

Sample 

Sample

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


  1. dialogState(ACTIVE)
5

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)
6holdCallThis command allows a user to hold a call

Sample

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

Sample

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

Sample

JS 
{
				"action": "logout",
				"parameter":
				{
					"reasonCode": "Logged Out",
					"userId": "448899",
					"clientCallbackFunction": eventCallback
				}
			};
  1. agentState
9muteThis command will mute the audio of call from agent side. 

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


10unmute

This command will unmute the audio of call from agent side. 


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


11SST (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


12SST_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,
					"numberToTransfer" : "00000000"					}
			}

Agent A

  1. dialogState(DROPPED)


Agent B

  1. newInboundCall
13ConsultCallThis command allows a user to initiate a consult call with another agent. Once the call is accepted by the other agent, the user can either transfer this call to the other agent or can drop the consult call. 
JS 
{
				"action": "makeConsult",
				"parameter":
				{
					"numberToConsult":"4488992",
					"clientCallbackFunction": eventCallback
				}

For Agent A:

  1. dialogState(Held)
  2. consultCall (Initiating)
  3. consultCall (Initiated)

 

For agent B:

  1. consultCall (Alerting)

14

ConsultCall_Queue

This command allows a user to initiate a consult call with another agent using Queue. Once the call is accepted by the other agent, the user can either transfer this call to the other agent or can drop the consult call. 

JS 
{
				"action": "makeConsultQueue",
				"parameter":
				{
					"numberToTransfer":"99887766",
					"queue":"65bb2dcbba1aab2d0a4742d6",
					"queueType":"ID",
					"clientCallbackFunction": eventCallback,
				}
			}

For Agent A:

  1. dialogState(Held)
  2. consultCall (Initiating)
  3. consultCall (Initiated)
  4. consultCall (Active)

 

For agent B:

  1. consultCall (Alerting)
15Consult Transfer

This command allows a user to merge / Bridge Customer Call with another agent. The Other agent must be in Call with First Agent.
JS 
{
				"action": "consultTransfer",
				"parameter":
				{
					"clientCallbackFunction": eventCallback
				}
			}

For Agent A:

  1. consultCall (Drop)
  2. dialogState(Drop)

 

For agent B:

  1. consultCall (Drop)
  2. dialogState(Active)
16SendDtmf

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
17Click To Call

This command will allow user to make call in cross domain like if the user domain is different then the FS JS API domain then user must send us window.postMessage that contains required parameters. 


  • callType
  • Destination_Number
  • calledNumber

Here above are dynamic values while SourceType value will remain static 

JS 
var obj = {
    "callType" : "audio",//audio/video/screenshare
    "Destination_Number":"1777",
    "calledNumber": "1777",
    "SourceType" : "CTI"
    }
    window.postMessage(obj, "*"); // "*" means sending to all origins
  1. outboundDialing(INITIATING, INITIATED)
18ConvertCall

This Command will allow the user to Enable / Disable Stream while in webrtc Call.
stream: video / screenshare

streamStatus: on / off

JS 
{
				"action": "convertCall",
				"parameter":
				{
					"dialogId": "c1cc4fb6-3676-123b-ea94-005056bc90cf",
					"clientCallbackFunction": eventCallback,
					"streamStatus" : streamStatus ,    //on , off
					"streamType" : streamType   //screenshare, video

				}
			}
  1. mediaConversion(success)

 

19Silent MonitorThis command allows the supervisor to silently monitor a call.

JS 
{
				"action": "silentMonitor",
				"parameter":
				{
					"calledNumber":  "1777",
                    "callType": "audio",
                    "Destination_Number": "1777",
					"service_Identifier": serviceIdentifier,
					"clientCallbackFunction": eventCallback
				}
			}
  1. outboundDialing(INITIATING, INITIATED)
  2. dialogState (ACTIVE)

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,
			"wrapUpItems": 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",
            "mediaType":null,
            "callOriginator" : "webrtc"
        }
    }
}

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,
			"wrapUpItems": 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
                }
            ],
            "mediaType":null,
            "callOriginator" : "webrtc"
        }
    }
}
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,
			"wrapUpItems": 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
                }
            ],
            "mediaType":null,
            "callOriginator" : "webrtc"
        }
    }
}
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,
			"wrapUpItems": 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
                }
            ],
            "mediaType":null,
            "callOriginator" : "webrtc"
        }
    }
}
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 

9mediaConversionThis Event will be triggered when any Participant of the webrtc call enable/disable a stream
JS 
{
    "event" : "mediaConversion",
    "status" : null,
    "loginId" : loginid,
    "dialog": {
        "id": null,
        "eventRequest" : null,
        "stream" : null,
        "streamStatus" :null,   
        "errorReason" : null, 
        "timeStamp" : null 
    }
}

status: error/success
event request: local / remote
stream:  video / screenshare
streamStatus: on / off

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
1callTypecallTypes =




{




inboundType : "OTHER_IN",




outboundType : "OUT",




consultType : "CONSULT",




consultTransferType : "CONSULT_TRANSFER",




}
JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close