UCS API Upgrade Guide

This document provides information for migrating from the Web Services API (UCS/TEXT) to the UCS API.

REST Resources

The UCS API is a REST API, therefore it models resources.

Except for the DELETERECORD and KEEPALIVE, all requests and responses manipulate a call resource.

In addition, some operations operate on sub-collection resources of the call:

Sub-collection resources	Multiple sub-items support
/calls/{id}/conferences	Yes (each sub-item is a conferenced call)
/calls/{id}/playMedias	Yes (each sub-item is a file in the playlist)
/calls/{id}/recordMedias	No
/calls/{id}/generateTones	No
/calls/{id}/detectTones	No
/calls/{id}/generateDigits	No
/calls/{id}/detectDigits	No
/calls/{id}/synthesizeSpeechs	(No)
/calls/{id}/recognizeSpeechs	No

Most call sub-collection resources currently support having only a Single sub-item (0 or 1 more precisely); in this case, if 1 sub-item already exists, creating a new sub-item will delete the currently existing one before adding the newly created one. This Single sub-item support may evolve to Multiple sub-items support in the future (especially with generateTones, generateDigits, synthesizeSpeechs).

Requests

Messages sent by the Client to NG Media Server.

Command (Web Services)	operationId	Method	Path	Remarks
-	GetCalls	GET	/calls
MAKECALL	MakeCall	POST	/calls	The call id is now allocated by the server and returned in the Response
-	GetCall	GET	/calls/{id}
CLEARCALL	ClearCall	POST	/calls/{id}/clear
-	AcceptCall	POST	/calls/{id}/accept	The Client is now responsible to accept the call
ANSWERCALL	AnswerCall	POST	/calls/{id}/answer
DEFLECTCALL	DeflectCall	POST	/calls/{id}/deflect
HOLDCALL	HoldCall	POST	/calls/{id}/hold
RETRIEVECALL	RetrieveCall	POST	/calls/{id}/retrieve
SINGLESTEPTRANSFERCALL	SingleStepTransferCall	POST	/calls/{id}/singleStepTransfer
TRANSFERCALL	TransferCall	POST	/calls/{id}/transfer
REMOTEANSWERCALL?	RemoteAnswerCall	POST	/calls/{id}/remoteAnswer
REMOTEHOLDCALL?	RemoteHoldCall	POST	/calls/{id}/remoteHold
REMOTERETRIEVECALL?	RemoteRetrieveCall	POST	/calls/{id}/remoteRetrieve
-	GetCallConferences	GET	/calls/{id}/conferences
ADDTOCONF	AddCallConference	POST	/calls/{id}/conferenceAdd
REMFROMCONF	RemoveCallConference	POST	/calls/{id}/conferenceRemove
-	GetCallPlayMedias	GET	/calls/{id}/playMedias
PLAY	StartCallPlayMedia	POST	/calls/{id}/playMedias
-	GetCallPlayMedia	GET	/calls/{id}/playMedias/{mediaId}
STOPPLAY	StopCallPlayMedia	POST	/calls/{id}/playMediaStop
SETPLAYVOLUME	SetVolumeCallPlayMedia	POST	/calls/{id}/playMediaSetVolume
-	GetCallRecordMedias	GET	/calls/{id}/recordMedias
RECORD	StartCallRecordMedia	POST	/calls/{id}/recordMedias
-	GetCallRecordMedia	GET	/calls/{id}/recordMedias/{mediaId}
STOPRECORD	StopCallRecordMedia	POST	/calls/{id}/recordMediaStop
PAUSERECORD	PauseCallRecordMedia	POST	/calls/{id}/recordMediaPause
RESUMERECORD	ResumeCallRecordMedia	POST	/calls/{id}/recordMediaResume
DELETERECORD *	DeleteCallRecording	DELETE	/call_recordings/{call_recordingId}
-	GetCallGenerateDigits	GET	/calls/{id}/generateDigits
SENDDTMF	StartCallGenerateDigit	POST	/calls/{id}/generateDigits
-	GetCallGenerateDigit	GET	/calls/{id}/generateDigits/{digitId}
-	StopCallGenerateDigit	POST	/calls/{id}/generateDigitStop
-	GetCallDetectDigits	GET	/calls/{id}/detectDigits
-	StartCallDetectDigit	POST	/calls/{id}/detectDigits	The client is now responsible to start DTMF detection on the call
-	GetCallDetectDigit	GET	/calls/{id}/detectDigits/{digitId}
-	StopCallDetectDigit	POST	/calls/{id}/detectDigitStop
-	GetCallGenerateTones	GET	/calls/{id}/generateTones
SENDTONE	StartCallGenerateTone	POST	/calls/{id}/generateTones	{ id: ..., Tone: ..., Duration: ..., Country: ... }
-	GetCallGenerateTone	GET	/calls/{id}/generateTones/{toneId}
STOPSENDTONE	StopCallGenerateTone	POST	/calls/{id}/generateToneStop
-	GetCallDetectTones	GET	/calls/{id}/detectTones
RECOGNIZETONE	StartCallDetectTone	POST	/calls/{id}/detectTones
-	GetCallDetectTone	GET	/calls/{id}/detectTones/{toneId}
STOPRECOGNIZETONE	StopCallDetectTone	POST	/calls/{id}/detectToneStop
-	GetCallSynthesizeSpeechs	GET	/calls/{id}/synthesizeSpeechs
SPEAK	StartCallSynthesizeSpeech	POST	/calls/{id}/synthesizeSpeechs
-	GetCallSynthesizeSpeech	GET	/calls/{id}/synthesizeSpeechs/{speechId}
STOPSPEAK	StopCallSynthesizeSpeech	POST	/calls/{id}/synthesizeSpeechStop
-	GetCallRecognizeSpeechs	GET	/calls/{id}/recognizeSpeechs
RECOGNIZE	StartCallRecognizeSpeech	POST	/calls/{id}/recognizeSpeechs
-	GetCallRecognizeSpeech	GET	/calls/{id}/recognizeSpeechs/{speechId}
STOPRECOGNIZE	StopCallRecognizeSpeech	POST	/calls/{id}/recognizeSpeechStop
KEEPALIVE **	-	-	-

* : DELETERECORD is supported starting with Release 6.1.1:

• The {call_recordingId} holds the URL encoded filename. The "." character must be explicitly URL encoded (%2E).

With Release 6.1:

• Workaround #1: use the Web Services API to perform DELETERECORD.
• Workaround #2: if the client application is located on the same PC than NG Media Server, the client application may be able to delete recorded files directly.

** : KEEPALIVE is currently not supported under the UCS API:

• Workaround #1: instead the UCS API is using the Ping/Pong frames of the WebSocket protocol.
• Workaround #2: the client application can also use a GET /ngms/ws/product to query the version and build of the NG Media Server

  { "method":"GET", "path":"/product", "id": "123" }
  

MAKECALL is now a 2 step process:

1. The Client sends a request : POST /calls, providing a request id, but without a call id
2. The Client later receives a response, with the matching request id, and with the body containing the call id allocated by the server.

TRACE and STOPTRACE are now part of the /traces collection.

Responses

Communications are based on messages exchanged over networks:

• Requests from the Client can send messages to the network.
• Messages received from the network can deliver notifications to the Client.

Typically, a request does not need a response, because if the request is well-formed, the response should be 200 OK. And if the operation cannot complete (because a state changed in the meantime, like remote disconnected), then a notification should report the state change.

One exception is MAKECALL:

the MAKECALL request requires a response, because MAKECALL creates a new /call resource on the server, and the response is used to convey the id of the created resource back. Also a response may be requested with other requests for debugging purposes, like in development, but it should not be needed in production.

Notifications

Messages sent by NG Media Server to the Client.

Event (Web Services)	operationId	Method	Path	Remarks
DIALIN	onMakeCall	POST	/calls
-	onModifyCall	PATCH	/calls/{id}	{ Op: acceptAck }
RINGING	onModifyCall	PATCH	/calls/{id}	{ Op: accept, State: delivered }
-	onModifyCall	PATCH	/calls/{id}	{ Op: deflectAck }
-	onModifyCall	PATCH	/calls/{id}	{ Op: deflect }
CONNECTED	onModifyCall	PATCH	/calls/{id}	Incoming call. { Op: answerAck, State: connected }
CONNECTED	onModifyCall	PATCH	/calls/{id}	Outgoing call. { Op: answer, State: connected }
DISCONNECTED	onModifyCall	PATCH	/calls/{id}	Cleared localy. { Op: clearAck, State: disconnected, LocalClear: true }
DISCONNECTED	onModifyCall	PATCH	/calls/{id}	Cleared remotely. { Op: clear, State: disconnected, LocalClear: true }
HOLDCALLENDED Success:true	onModifyCall	PATCH	/calls/{id}	{ Op: holdAck, LocalHold: true }
HOLDCALLENDED Success:false	onModifyCall	PATCH	/calls/{id}	{ Op: holdRej }
-	onModifyCall	PATCH	/calls/{id}	{ Op: hold, RemoteHold: true }
RETRIEVECALLENDED Success:true	onModifyCall	PATCH	/calls/{id}	{ Op: retrieveAck, LocalHold: false }
RETRIEVECALLENDED Success:false	onModifyCall	PATCH	/calls/{id}	{ Op: retrieveRej }
-	onModifyCall	PATCH	/calls/{id}	{ Op: retrieve, RemoteHold: false }
TRANSFERCALLENDED Success:true	onModifyCall	PATCH	/calls/{id}	{ Op: transferAck }
TRANSFERCALLENDED Success:false	onModifyCall	PATCH	/calls/{id}	{ Op: transferRej }
SINGLESTEPTRANSFERCALLENDED Success:true	onModifyCall	PATCH	/calls/{id}	{ Op: singleStepTransferAck }
SINGLESTEPTRANSFERCALLENDED Success:false	onModifyCall	PATCH	/calls/{id}	{ Op: singleStepTransferRej }
UPDATE	onModifyCall	PATCH	/calls/{id}	{ Op: transfer }
DTMF	onModifyCall	PATCH	/calls/{id}/detectDigits/{digitId}	{ Digit: ... }
TONE	onModifyCall	PATCH	/calls/{id}/detectTones/{toneId}	{ Tone: ... }
CALLANALYSIS	onModifyCall	PATCH	/calls/{id}	{ Op: cpa }
LINKDOWN (5.3)	onModifyCall	PATCH	/calls/{id}	{ Op: linkDown, LinkUp: false }
LINKUP (5.3)	onModifyCall	PATCH	/calls/{id}	{ Op: linkUp, LinkUp: true }
- (6.1.7)	onModifyCall	PATCH	/calls/{id}	{ Op: webClientUp, Web: true, Video: ..., Audio: ... }
- (6.1.7)	onModifyCall	PATCH	/calls/{id}	{ Op: webClientDown, Web: false, Video: ..., Audio: ... }
- (7)	onModifyCall	PATCH	/calls/{id}	{ Op: failover, ToAddress: ..., FromAddress: ..., Transport: ... }
-	onDeleteCall	DELETE	/calls/{id}
PLAYENDED	onCompleteCallPlayMedia	DELETE	/calls/{id}/playMedias/{mediaId}	{ State: completed, Success: ..., Comment: ... }
RECORDENDED	onCompleteCallRecordMedia	DELETE	/calls/{id}/recordMedias/{mediaId}	{ State: completed, Success: ..., Comment: ... }
SENDTONEENDED	onCompleteCallGenerateTone	DELETE	/calls/{id}/generateTones/{toneId}	{ State: completed, Success: ..., Comment: ... }
-	onCompleteCallDetectTone	DELETE	/calls/{id}/detectTones/{toneId}	{ Success: ..., Comment: ... }
-	onCompleteCallGenerateDigit *	DELETE	/calls/{id}/generateDigits/{digitId}	Not yet implemented in 6.1. { State: completed, Success: ..., Comment: ... }
-	onCompleteCallDetectDigit	DELETE	/calls/{id}/detectDigits/{digitId}	{ Success: ..., Comment: ... }
SPEAKENDED	onCompleteCallSynthesizeSpeech	DELETE	/calls/{id}/synthesizeSpeechs/{speechId}	{ State: completed, Success: ..., Comment: ... }
RECOGNIZEENDED	onCompleteCallRecognizeSpeech	DELETE	/calls/{id}/recognizeSpeechs/{speechId}	{ State: completed, Success: ..., Choice: ..., Confidence: ..., Instance: ..., Input: ..., Content: ..., Comment: ... }

* : The onCompleteCallGenerateDigit is not yet implemented in 6.1.

The PATCH Method notifies that an event occurred on the call or a resource of the call. The event is provided in the Op parameter when the Path indicates a call. Updated call information (State, ...) is provided.

The DELETE Method notifies that the resource was deleted from the server.

However as the HTTP DELETE message typically has no body, for the widest compatibility, when an event leads to a resource deletion 2 messages are delivered instead of one:

1. An initial PATCH message is delivered to inform that the resource state changed (eg. disconnected) and with information contained in the body.
2. A DELETE message follows to inform that the resource was deleted from the server.

Parameters

Most parameters from the Web Services API were kept unchanged.

Exceptions:

• Caller/Called parameter name prefixes were renamed into From/To prefixes to natively match most recent protocols coming from the web standards (rfcs). The meaning is unchanged.

• Number parameter name postfixes were renamed into Uri (for example, CalledNumber was renamed into ToUri): the new names and meaning natively match most recent protocols coming from the web standards (rfcs). The meaning evolved from describing a phone Number to describing a Uri. To easily switch from a phone Number to a Uri, you can use the "callto" Uri scheme: the phone number 2000 can be expressed as the URL callto:2000. Note that this also perfectly matches numbers with some special characters, like callto:+12345678901 (number with E.164 international prefix), callto:34#2000 (number with a function code interpreted by a PBX or operator), or callto:bob (translated as sip:bob@host with SIP, the host being the remote domain of the trunk used). Phone Numbers support is still available, but Uri should be used instead. Version 6.0 up to 6.1.8 support only raw phone Numbers (numbers with an optional leading "+" sign followed by digits, "*" or "#" characters). Starting with version 6.1.9, 'visual-separator' characters are now supported in phone Numbers: space, ".", "-", "(", ")" are now accepted and are removed when dialing.

• The Cause parameter (in CLEARCALL request) was encoded as a 16-bit hexadecimal number with the format 0x34XX for Q.850 cause and 0x33YY for error protocol layer 1/2/3. It is now a signed integer with positive values representing a Q.850 cause (as a decimal number) and negative values representing other causes.

  Web Services API	UCS API
  0x3401	1
  0x3402	2
  ...	...
  0x347E	126
  0x347F	127
  0x3301	-1
  0x3302	-2
  0x3303	-3

• The UUI parameter was renamed into Uui. The UUI was encoded as an hexadecimal buffer. The Uui is now a string. The string must contain only characters between 0 and 255; JSON escaping rules are used to encode non printable characters. For example "\u0004Some Info" is used to indicate user information "Some Info" with protocol discriminator 4 (IA5 characters). This is equivalent to hexadecimal buffer 04536F6D6520496E666F.

• The Filename parameter was renamed into Uri.

• The CallId parameter (in MAKECALL request) was renamed into id (after Release 6.1). This call id is optional and SHOULD not be used. When not provided, the server will allocate a unique negative number. If the call id is provided, it must be unique for the calls resources and it must not be a negative number. For compatibility with Release 6.1, the legacy name CallId may be used.

  { "method":"POST", "path":"/calls", "body":{"ToUri":"callto:2005", "CallId":"myAppGeneratedCallId"} }
  

• An optional id parameter can be provided in playMedias, recordMedias, generateTones, detectTones, generateDigits, detectDigits, synthesizeSpeechs, recognizeSpeechs. When not provided, the server will allocate a unique negative number. If the id is provided, it must be unique for the resource of that call and it must not be a negative number.

• The Key parameter (in DTMF notification) was renamed into Digit.

• The Tone parameter (in SENDTONE request) accepts tone names in addition to tone frequency (in hertz).

  Tone names
  busy
  callWaiting
  congestion
  ringing
  dial
  payphoneRecognition
  record
  ringing
  specialInformation
  pay

• The Country parameter (in SENDTONE request) was added in Release 6.2. When a tone name is used, the Country parameter enables to generate the tone for the indicated country. This value should be ISO 3166-1 Alpha-2 code or an international phone number or prefix in E.164 format. If the Country parameter is not specified, the default country for the computer applies.

  Country format	Example
  ISO 3166-1 Alpha-2 code (recommended)	US (United States), GB (United Kingdom), FR (France), DE (Germany), ...
  ISO 3166-1 Alpha-3 code	USA (United States), GBR (United Kingdom), FRA (France), DEU (Germany), ...
  County name (for test purposes only*)	United States, United Kingdom, France, Germany, ...
  International phone number or prefix (E.164)	+1 (United States**), +44 (United Kingdom), +33 (France), +49 (Germany), ...

  *: County names may use varying spellings, it is not a reliable method for production purposes.

  **: Numbers in the North American Numbering Plan (NANP) all start with the +1 prefix (the NANP includes the United States, Canada and Caribbean nations). To select the right country, +1 should be followed by the three-digit area code. For example +1212 is a prefix in the United States (New York), +1416 in Canada (Ontario), +1787 in Puerto Rico, ...

• In MAKECALL request, the CallAnalysis parameter was removed. Instead the Events parameter now enables to subscribe for Call Progress and Call Analysis. Pass value cp for Call Progress, ca for Call Analysis, cp ca for both.

  { "method":"POST", "path":"/calls", "body":{"ToUri":"callto:2005", "Events":"cp ca"} }
  

• In CALLANALYSIS notification, The Detected parameter was renamed into Cpa.

• In CALLANALYSIS notification, the Recording parameter for the AnsweringMachine detection was removed. Instead the Cpa parameter now reports AnsweringMachine.Message and AnsweringMachine.Recording. The generic '.' mechanism may be used in the future to report second (and more) levels of precision with the Cpa results.

• In ADDTOCONF request, the CallId and DataPath parameters were modified. The main CallId is now part provided in the Path, as with all other request. The Main DataPath parameter is still available as the optional DataPath parameter, but it is now the only DataPath parameter. The Participants CallId and DataPath are now available in a separate Participants parameter. The Participants parameter is an array of id (call id) and optional DataPath. The optional ListenOnly parameter is still available.

  { "method":"POST", "path":"/calls/1/conferenceAdd", "body":{"ListenOnly":true, "Participants":[{"id":"-1"}, {"id":"-2"}]} }
  

• In REMFROMCONF request, it is now possible to partly remove conference interconnections; in this case, the optional Participants parameter must be provided. The Participants parameter is an array of id (call id) and it explicitly indicates the conference interconnections that must be removed.

  { "method":"POST", "path":"/calls/1/conferenceRemove", "body":{"Participants":[{"id":"-1"}, {"id":"-2"}]} }
  

• An optional State parameter can be reported on notifications with playMedias, recordMedias, generateTones, detectTones, generateDigits, detectDigits, synthesizeSpeechs, recognizeSpeechs resources. When not provided, the default assumed value is completed. When completed, this indicates that the operation on the resource is now finished. In future versions other State value may be reported to notify of progress on the resource (like a PATCH may be received with a state indicating queued, started). When the State value is not understood, the other parameters may be ignored.

• ToDo: --- Listen/Subscribe for digits and Digit(DTMF) event : is it part of the call ?!

• ToDo: --- Listen/Subscribe for calls and other events

New in the UCS API

The UCS API introduces some new capabilities, like to deliver PBX server functionalities.

News:

• Call Accept request (New + Change): incoming calls were automatically accepted with the Web Services API, no action was required. Now incoming calls must be accepted by the application (request POST /calls/{id}/accept). When accepting a call, the caller is notified that the remote was reached - the call is ringing - and a ringback tone is typically received by the caller. Now:
  • by default applications should accept incoming calls as soon as the call is reported (notification POST /calls)
  • when acting as an intermediate element in the call path (like a PBX), call acceptance may be forwarded instead: the incoming call leg may be accepted only once the outgoing call leg is ringing (notification PATCH /calls/{id} with State: ringing)
  • when a call is reported and when the call should be immediately answered or cleared, the call should not need to be accepted then.
• ToDo: --- HopCounter
• ToDo: --- Call Redirection notification
• ToDo: --- Call Hold notification