Genesys Softphone Connector

Version: 2.0

Methods

POST /audio - Control audio devices

Control the available audio devices. You can mute/unmute the microphone or change the volume of the audio devices.

Consumes

This API call consumes the following media types via the Content-Type request header:

• application/json

Request body

Body Parameter — devices (required)

Responses

Code	Reason
200	OK
400	Bad Request
403	Forbidden
404	Not Found

DELETE /calls - Release an active call

Release an active call. This request should only be used in a disaster recovery situation if you need to delete false calls.

Responses

Code	Reason
200	OK
400	Bad Request
403	Forbidden
404	Not Found

DELETE /register - Stop the SIP or WebRTC session

Stop the current SIP or WebRTC connection. Calling this endpoint while a connection is already started will drop existing calls (if any) and close the connection. For a graceful behavior, it is recommended to check that no active call exist through GET /session before calling it.

Responses

Code	Reason
200	OK
400	Bad Request
403	Forbidden
404	Not Found

POST /register - Start a SIP or WebRTC session

Start a SIP or WebRTC connection. For WebRTC, this request provides the Softphone with the token used for OAuth authentication. Calling this endpoint will have the same effect as calling the DELETE /register and then restart the connection.

Responses

Code	Reason
200	OK
400	Bad Request
403	Forbidden
404	Not Found

DELETE /session - Close session

Close the current session, which stops all SIP or WebRTC connections. Use this request when an agent logs out.

Responses

Code	Reason
200	OK
400	Bad Request
403	Forbidden
404	Not Found

GET /session - Get session information

Get session information about the Softphone, including connections, calls and audio states.

Return type

session

Example data

Content-Type: application/json

{
  "devices" : {
    "speaker" : {
      "volume" : 8,
      "name" : "name",
      "muted" : true
    },
    "microphone" : {
      "volume" : 60,
      "name" : "name",
      "muted" : true
    },
    "headset_used" : true
  },
  "phone" : {
    "local_mos" : 5.962134,
    "rtt_ms" : 5,
    "calls" : [ {
      "state" : "UNKNOWN",
      "uuid" : "uuid"
    }, {
      "state" : "UNKNOWN",
      "uuid" : "uuid"
    } ],
    "vq_alarm_on" : true,
    "local_inter_mos" : 1.4658129
  },
  "connectivities" : {
    "protocol" : "udp",
    "connections" : [ {
      "server" : "server",
      "state" : "NONE",
      "user" : "user"
    }, {
      "server" : "server",
      "state" : "NONE",
      "user" : "user"
    } ]
  },
  "status" : "INITIALIZING"
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

• application/json

Responses

Code	Reason	Value
200	OK	session
400	Bad Request
403	Forbidden
404	Not Found

POST /session - Update session

Update the current session with your configuration for the SIP Endpoint and Softphone options. Use this request once when your client application initializes.

Consumes

This API call consumes the following media types via the Content-Type request header:

• application/json

Request body

Body Parameter — config (required)

Responses

Code	Reason
200	OK
400	Bad Request
403	Forbidden
404	Not Found

Models

call

Property	Type	Required	Description
uuid	String	No	The unique ID for the call. This ID comes from the "X-Genesys-CallUUID" header of the SIP session.
state	String	No	The state of the call. Possible values are: UNKNOWN ALETING CONNECTED DISCONNECTED IN_PROGRESS HELD MEDIA_OFFER OFFER_WAITING MEDIA_ACCEPTED MEDIA_REJECTED RINGING VQ_ALARM VQ_ALARM_OFF

config

Property	Type	Required	Description
options	config_options	No	Configuration options for the Softphone application.
connectivities	connectivities	No	The connections and protocols associated with this call.

config_options

Property	Type	Required	Description
sipendpoint	Object	No	Use this property to override Genesys Softphone options when provisioning the application. You must specify the option as <domain>.<section>.<setting> For example, to override the ringing_file setting in the session section, configure policy.session.ringing_file in your application provisioning. See the options reference for a list of Genesys Softphone settings.
softphone	config_options_softphone	No	Configuration options specific to Softphone application.

config_options_softphone

Property	Type	Required	Description
session_expire	Integer	No	The timeout, in seconds, for the Softphone to wait for the 'GetSession' service before ending the current session. The range of valid values is 0-300. If the provided value is out of range, it will be set to 300. Default value is 30.
enforce_headset_usage	Boolean	No	Specifies whether the SIP Endpoint must wait for the detection of the headset that is configured in the headset_name option before finalizing initialization. The agent remains logged out until the headset is detected.
username	String	No	This property is used only for WebRTC connectivity for identifying current session.

connection

Property	Type	Required	Description
server	String	No	For SIP Server, the format is <sipServerName>:<sipServerPort>. For SRV resolution, this property specifies the SRV record without including the port number in the server's URI.
user	String	No	The DN for the agent.
state	String	No	The state of the connection. Possible values are: NONE STANDALONE DISABLED TRYING FAILED READY SHUTDOWN

connectivities

Property	Type	Required	Description
protocol	String	No	The protocol used for SIP (udp or tcp) or WebRTC (https) connections.
connections	array[connection]	No	The Softphone's configured connections.

devices

Property	Type	Required	Description
headset_used	Boolean	No	The value is true if the agent is using a headset.
devices_speaker	devices_speaker	No	The speaker associated with the device.
microphone	devices_microphone	No	The microphone associated with the device.

devices_microphone

Property	Type	Required	Description
name	String	No	The microphone device name.
volume	Integer	No	The microphone volume.
muted	Boolean	No	Specifies whether the microphone is muted.

devices_speaker

Property	Type	Required	Description
name	String	No	The speaker device name.
volume	Integer	No	The speaker volume.
muted	Boolean	No	Specifies whether the speaker is muted.

phone

Property	Type	Required	Description
vq_alarm_on	Boolean	No	The value is true if the Voice Quality alarm is on. This is only applicable if VQ is activated in the SIP Endpoint options.
local_inter_mos	Float	No	The local Mean Opinion Score (MOS — a measure of reported network quality ratings) for the last interval. This is only applicable if VQ is activated in the SIP Endpoint options.
local_mos	Float	No	The local MOS for the entire call segment. This is only applicable if VQ is activated in the SIP Endpoint options.
rtt_ms	Integer	No	The round-trip time in milliseconds. This is only applicable if VQ is activated in the SIP Endpoint options.
calls	array[call]	No	The calls associated with this phone.

session

Property	Type	Required	Description
status	String	No	The Softphone status. Possible values ares: INITIALIZING - The Softphone is waiting for connections to register and is not ready for phone calls. INITIALIZED - The Softphone is connected, configured, and ready for phone calls. WAITING_HEADSET - The Softphone is waiting to detect the agent's headset before registering connections.
connectivities	connectivities	No	The connections and protocols associated with this session.
devices	devices	No	The devices associated with this session.
phone	phone	No	The phone associated with this session.

Example

The following log contains examples of HTTP requests and responses between Genesys Softphone and a client.

####
#### Agent login
####

GET /softphone/v2/session HTTP/1.1
Accept: */*
Origin: http://bsgwsfanch:8080
X-CSRF-TOKEN: d3c1f001-8f8b-4ab7-b016-5312d24b5f79
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Referer: http://bsgwsfanch:8080/ui/ad/v1/index.html
Accept-Encoding: gzip, deflate, br
Accept-Language: fr-FR, fr; q=0.9, en-US; q=0.8, en; q=0.7
Host: 127.0.0.1:8654
Connection: Keep-Alive

HTTP/1.1 403 Forbidden 
Access-Control-Allow-Origin: http://bsgwsfanch:8080
Access-Control-Allow-Credentials: true
Set-Cookie:SEPSESSIONID=8A13B0F6-9152-42A7-B10A-9F4DE731E1D3; HttpOnly; SameSite=None; Secure; Path=/softphone/v2/
Cache-Control:no-store
X-Content-Type-Options:nosniff
Access-Control-Expose-Headers:X-Genesys-Softphone-Version
X-Genesys-Softphone-Version:9.0.013.01  (Windows 10.0.18363)
Content-Length:2
Content-Type:application/json; charset=UTF-8

{}


POST /softphone/v2/session HTTP/1.1
Accept: */*
Origin: http://bsgwsfanch:8080
X-CSRF-TOKEN: d3c1f001-8f8b-4ab7-b016-5312d24b5f79
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Referer: http://bsgwsfanch:8080/ui/ad/v1/index.html
Accept-Encoding: gzip, deflate, br
Accept-Language: fr-FR, fr; q=0.9, en-US; q=0.8, en; q=0.7
Cookie: SEPSESSIONID=8A13B0F6-9152-42A7-B10A-9F4DE731E1D3
Content-Type: application/json; charset=utf-8
Host: 127.0.0.1:8654
Content-Length: 1809
Expect: 100-continue

{"options":{"sipendpoint":{"policy.connector.auto_restart":"1"},"softphone":{"session_expire":60}},"connectivities":{"protocol":"udp","connections":[{"server":"135.39.45.32:5060","user":"5320"}]}}


HTTP/1.1 200 OK 
Access-Control-Allow-Origin: http://bsgwsfanch:8080
Access-Control-Allow-Credentials: true
X-Content-Type-Options:nosniff
Access-Control-Expose-Headers:X-Genesys-Softphone-Version
X-Genesys-Softphone-Version:9.0.013.01  (Windows 10.0.18363)
Content-Length:2
Content-Type:application/json; charset=UTF-8

{}


POST /softphone/v2/register HTTP/1.1
Accept: */*
Origin: http://bsgwsfanch:8080
X-CSRF-TOKEN: d3c1f001-8f8b-4ab7-b016-5312d24b5f79
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Referer: http://bsgwsfanch:8080/ui/ad/v1/index.html
Accept-Encoding: gzip, deflate, br
Accept-Language: fr-FR, fr; q=0.9, en-US; q=0.8, en; q=0.7
Cookie: SEPSESSIONID=8A13B0F6-9152-42A7-B10A-9F4DE731E1D3
Authorization: Bearer TestJwtTokenInAuthorization_Bearer
Host: 127.0.0.1:8654
Content-Length: 0

HTTP/1.1 200 OK 
Access-Control-Allow-Origin: http://bsgwsfanch:8080
Access-Control-Allow-Credentials: true
X-Content-Type-Options:nosniff
Access-Control-Expose-Headers:X-Genesys-Softphone-Version
X-Genesys-Softphone-Version:9.0.013.01  (Windows 10.0.18363)
Content-Length:2
Content-Type:application/json; charset=UTF-8

{}


GET /softphone/v2/session HTTP/1.1
Accept: */*
Origin: http://bsgwsfanch:8080
X-CSRF-TOKEN: d3c1f001-8f8b-4ab7-b016-5312d24b5f79
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Referer: http://bsgwsfanch:8080/ui/ad/v1/index.html
Accept-Encoding: gzip, deflate, br
Accept-Language: fr-FR, fr; q=0.9, en-US; q=0.8, en; q=0.7
Cookie: SEPSESSIONID=8A13B0F6-9152-42A7-B10A-9F4DE731E1D3
Host: 127.0.0.1:8654


HTTP/1.1 200 OK 
Access-Control-Allow-Origin: http://bsgwsfanch:8080
Access-Control-Allow-Credentials: true
Cache-Control:no-store
X-Content-Type-Options:nosniff
Access-Control-Expose-Headers:X-Genesys-Softphone-Version
X-Genesys-Softphone-Version:9.0.013.01  (Windows 10.0.18363)
Content-Length:383
Content-Type:application/json; charset=UTF-8

{"status":"INITIALIZED","connectivities":{"protocol":"udp","connections":[{"server":"135.39.45.32:5060","user":"5320","state":"READY"}],"sep_connection_status":""},"devices":{"headset_used":false,"speaker":{"name":"VK248 (Intel(R) Display Audio)","volume":100,"muted":false},"microphone":{"name":"Microphone Array (Realtek(R) Audio)","volume":77,"muted":false}},"phone":{"calls":[]}}


####
#### Softphone is registered (connection state is READY). Send regular GET /softphone/v2/session every one or two seconds as a keep alive
####

...
...

####
#### Agent logout and exit
####


DELETE /softphone/v2/register HTTP/1.1
Accept: */*
Origin: http://bsgwsfanch:8080
X-CSRF-TOKEN: d3c1f001-8f8b-4ab7-b016-5312d24b5f79
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Referer: http://bsgwsfanch:8080/ui/ad/v1/index.html
Accept-Encoding: gzip, deflate, br
Accept-Language: fr-FR, fr; q=0.9, en-US; q=0.8, en; q=0.7
Cookie: SEPSESSIONID=8A13B0F6-9152-42A7-B10A-9F4DE731E1D3
Host: 127.0.0.1:8654
Content-Length: 0


HTTP/1.1 200 OK 
Access-Control-Allow-Origin: http://bsgwsfanch:8080
Access-Control-Allow-Credentials: true
X-Content-Type-Options:nosniff
Access-Control-Expose-Headers:X-Genesys-Softphone-Version
X-Genesys-Softphone-Version:9.0.013.01  (Windows 10.0.18363)
Content-Length:2
Content-Type:application/json; charset=UTF-8

{}


DELETE /softphone/v2/session HTTP/1.1
Accept: */*
Origin: http://bsgwsfanch:8080
X-CSRF-TOKEN: d3c1f001-8f8b-4ab7-b016-5312d24b5f79
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36
Referer: http://bsgwsfanch:8080/ui/ad/v1/index.html
Accept-Encoding: gzip, deflate, br
Accept-Language: fr-FR, fr; q=0.9, en-US; q=0.8, en; q=0.7
Cookie: SEPSESSIONID=8A13B0F6-9152-42A7-B10A-9F4DE731E1D3
Host: 127.0.0.1:8654
Content-Length: 0

HTTP/1.1 200 OK 
Access-Control-Allow-Origin: http://bsgwsfanch:8080
Access-Control-Allow-Credentials: true
Set-Cookie:SEPSESSIONID=; HttpOnly; SameSite=None; Secure
X-Content-Type-Options:nosniff
Access-Control-Expose-Headers:X-Genesys-Softphone-Version
X-Genesys-Softphone-Version:9.0.013.01  (Windows 10.0.18363)
Content-Length:2
Content-Type:application/json; charset=UTF-8

{}