Jump to: navigation, search

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

{}
This page was last edited on July 7, 2021, at 12:57.
Comments or questions about this documentation? Contact us for support!