TAPI Migration Guide

!!! THIS DOCUMENT IS UNDER CONSTRUCTION !!!

This document provides information for migrating from the Microsoft Telephony API (TAPI) to the UCS API.

Key Differences

TODO: The Telephony Application Programming Interface (TAPI) is a Microsoft Windows API, which provides Computer Telephony Integration and enables PCs running Microsoft Windows to control and monitor telephone services.

• Translating TAPI Functions Call functions Caps functions Info and Status functions Other functions

• Translating TAPI LINE_REPLY

• Translating TAPI error ocdes

• Translating TAPI callbacks

• Translating Audio Playback and Recording

• Translating Speech Services

• Basic Access

  • Initializing
  • Requesting notification
  • Calling
  • Clearing

  Differences	TAPI	UCS API
  API	Win32 (TAPI DLL)	Web Services API (/ngms/ucs)
  Language	C	Any
  Platform	Windows	Windows, Linux (Ubuntu)
  Component	OS	Network
  Publisher	Microsoft	NG Media

TAPI Resources

TAPI	UCS API
Provider	-
Application	-
Line	-
Address	-
Phone	-
Call	Call

The UCS API is based on Call resources, providing a simple and efficient model.

Legacy TAPI concepts of multiple Line, Phone, Address were removed, as well as multiple Provider and Application.

A client Application connects to the UCS API of a NG Media Server using a WebSocket (/ngms/ucs). The connection is typically secured (WSS) and uses credentials.

The UCS API may be seen as equivalent to a single TAPI Provider supporting one TAPI Line per Server and zero TAPI Phone, the TAPI Line supporting a single TAPI Address supporting multiple Calls.

WebRTC Softphone support may be seen as an alternative to TAPI Phone resource support.

REST SIP Registration resources (/sip_registrations/{id}) identify SIP phones and WebRTC phones registered with the NG Media SBC.

Other TAPI Concepts

TAPI	UCS API
Conference Calls	TAPI Conference Call concept (a specific call handle representing the conference) was deprecated. The UCS API only uses normal calls that can be conferenced together and provide fine mixing matrix options.
Device Specific	TAPI Device Specific concept (opaque buffer for provider specific extensions) was deprecated. The UCS API is extensible by design with REST: new Resources and Properties can be added.
Asynchronous Function Completion	Some TAPI Functions are synchronous, some other are asynchronous (use LINE_REPLY to report the Asynchronous Function Completion). With the UCS API, all functions are asynchronous by design (because executed remotely), but often the Function Completion is not required (except for MakeCall), . See Responses below for more details.
Privileges	TAPI Privilege concept (LINECALLPRIVILEGE_ OWNER and MONITOR) is currently not used. The UCS API provides OWNER privileges.
Messages	TAPI Messages concept (lineCallbackFunc, lineGetMessage), notifying events with only four 32-bits integers (dwMessageID, dwParam1, dwParam2, dwParam3) and often requiring to then read the updated data buffers using separate functions (lineGetCallInfo, ...), was superseded by notification messages carrying the updated data directly.
WAVE API	TAPI is designed for Call Control. Audio Playback and Recording was accessible through the WAVE API. The UCS API now integrates builtin Audio playback and Recording functionalities (including with playback queue, media encryption, stereo recording)
Speech API	TAPI is designed for Call Control. Speech Services (like for Speech Synthesis and Speech Recognition) was accessible through the Speech API (SAPI). The UCS API now integrates builtin support using Speech Services based on third party MRCPv2 servers, which is the industry standard.

REST Resources

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

Except for the DeleteCallRecording 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 (TAPI Line Device Functions)

Messages sent by the Client to NG Media Server.

Line Device Functions (TAPI)	operationId	Method	Path	Remarks
-	GetCalls	GET	/calls
lineMakeCall	MakeCall	POST	/calls	The call id is allocated by the server and returned in the Response
-	GetCall	GET	/calls/{id}
lineDrop	ClearCall	POST	/calls/{id}/clear
lineAccept	AcceptCall	POST	/calls/{id}/accept
lineAnswer	AnswerCall	POST	/calls/{id}/answer
lineRedirect	DeflectCall	POST	/calls/{id}/deflect
lineHold	HoldCall	POST	/calls/{id}/hold
lineUnhold	RetrieveCall	POST	/calls/{id}/retrieve
lineBlindTransfer	SingleStepTransferCall	POST	/calls/{id}/singleStepTransfer
lineCompleteTransfer LINETRANSFERMODE_TRANSFER	TransferCall	POST	/calls/{id}/transfer
-	RemoteAnswerCall	POST	/calls/{id}/remoteAnswer
-	RemoteHoldCall	POST	/calls/{id}/remoteHold
-	RemoteRetrieveCall	POST	/calls/{id}/remoteRetrieve
-	GetCallConferences	GET	/calls/{id}/conferences
lineCompleteTransfer LINETRANSFERMODE_CONFERENCE	AddCallConference	POST	/calls/{id}/conferenceAdd
lineAddToConference	AddCallConference	POST	/calls/{id}/conferenceAdd
lineRemoveFromConference	RemoveCallConference	POST	/calls/{id}/conferenceRemove
-	GetCallPlayMedias	GET	/calls/{id}/playMedias
(waveOutWrite)	StartCallPlayMedia	POST	/calls/{id}/playMedias
-	GetCallPlayMedia	GET	/calls/{id}/playMedias/{mediaId}
(waveOutReset)	StopCallPlayMedia	POST	/calls/{id}/playMediaStop
(waveOutSetVolume)	SetVolumeCallPlayMedia	POST	/calls/{id}/playMediaSetVolume
-	GetCallRecordMedias	GET	/calls/{id}/recordMedias
(waveInAddBuffer)	StartCallRecordMedia	POST	/calls/{id}/recordMedias
-	GetCallRecordMedia	GET	/calls/{id}/recordMedias/{mediaId}
(waveInReset)	StopCallRecordMedia	POST	/calls/{id}/recordMediaStop
(waveInStop)	PauseCallRecordMedia	POST	/calls/{id}/recordMediaPause
(waveInStart)	ResumeCallRecordMedia	POST	/calls/{id}/recordMediaResume
-	DeleteCallRecording	DELETE	/call_recordings/{call_recordingId}
-	GetCallGenerateDigits	GET	/calls/{id}/generateDigits
lineGenerateDigits	StartCallGenerateDigit	POST	/calls/{id}/generateDigits
-	GetCallGenerateDigit	GET	/calls/{id}/generateDigits/{digitId}
lineGenerateDigits lpszDigits=NULL	StopCallGenerateDigit	POST	/calls/{id}/generateDigitStop
-	GetCallDetectDigits	GET	/calls/{id}/detectDigits
lineMonitorDigits	StartCallDetectDigit	POST	/calls/{id}/detectDigits
-	GetCallDetectDigit	GET	/calls/{id}/detectDigits/{digitId}
lineMonitorDigits dwDigitModes=0	StopCallDetectDigit	POST	/calls/{id}/detectDigitStop
-	GetCallGenerateTones	GET	/calls/{id}/generateTones
lineGenerateTone	StartCallGenerateTone	POST	/calls/{id}/generateTones	{ Country: ... }
-	GetCallGenerateTone	GET	/calls/{id}/generateTones/{toneId}
lineGenerateTone dwToneMode=0	StopCallGenerateTone	POST	/calls/{id}/generateToneStop
-	GetCallDetectTones	GET	/calls/{id}/detectTones
lineMonitorTones	StartCallDetectTone	POST	/calls/{id}/detectTones
-	GetCallDetectTone	GET	/calls/{id}/detectTones/{toneId}
lineMonitorTones lpToneList=NULL	StopCallDetectTone	POST	/calls/{id}/detectToneStop
-	GetCallSynthesizeSpeechs	GET	/calls/{id}/synthesizeSpeechs
lineSendUserUserInfo cx_EncodeManufacturerSpecific_SpeakSpeak	StartCallSynthesizeSpeech	POST	/calls/{id}/synthesizeSpeechs
-	GetCallSynthesizeSpeech	GET	/calls/{id}/synthesizeSpeechs/{speechId}
lineSendUserUserInfo cx_EncodeManufacturerSpecific_SpeakStop	StopCallSynthesizeSpeech	POST	/calls/{id}/synthesizeSpeechStop	-
lineSendUserUserInfo cx_EncodeManufacturerSpecific_RecognizeRecognize	StartCallRecognizeSpeech	POST	/calls/{id}/recognizeSpeechs
-	GetCallRecognizeSpeech	GET	/calls/{id}/recognizeSpeechs/{speechId}
lineSendUserUserInfo cx_EncodeManufacturerSpecific_RecognizeStop	StopCallRecognizeSpeech	POST	/calls/{id}/recognizeSpeechStop

Line Device Functions (TAPI) currently not supported

Line Device Functions (TAPI)	Remarks
lineDial	❌ currently not supported
linePark	❌ currently not supported
lineUnpark	❌ currently not supported
linePickup	❌ currently not supported
lineForward	❌ currently not supported
lineCompleteCall	❌ currently not supported
lineUncompleteCall	❌ currently not supported
lineForward	❌ currently not supported
lineSecureCall	❌ currently not supported
lineSendUserUserInfo	❌ currently not supported
lineReleaseUserUserInfo	❌ currently not supported
lineGatherDigits	❌ currently not supported
lineMonitorMedia	❌ currently not supported
lineSetMediaMode	❌ currently not supported
lineSetCallData	❌ currently not supported
lineSetAppSpecific	❌ currently not supported
lineSetMediaControl	❌ currently not supported
lineSetTerminal	❌ currently not supported (to route the audio of a call on the microphone and speaker of a PC, conference a WebRTC call instead)
lineGetConfRelatedCalls	❌ not applicable (no TAPI conference call concept)
linePrepareAddToConference	❌ not applicable (no TAPI conference call concept)
lineSetupTransfer	split as HoldCall and then MakeCall
lineSetupConference	split as HoldCall and then MakeCall
lineSwapHold	split as HoldCall and then RetrieveCall
lineDevSpecific	❌ not applicable (no TAPI Device Specific context)
lineDevSpecificFeature	❌ not applicable (no TAPI Device Specific context)
lineDeallocateCall	❌ not applicable (disconnected calls are always released)
lineGetCallInfo	❌ not applicable (call info and status changed are notified)
lineGetCallStatus	❌ not applicable (call info and status changed are notified)
lineGetProviderList	❌ not applicable (no TAPI provider concept)
lineAddProvider	❌ not applicable (no TAPI provider concept)
lineRemoveProvider	❌ not applicable (no TAPI provider concept)
lineInitialize	❌ not applicable (no TAPI application concept)
lineInitializeEx	❌ not applicable (no TAPI application concept)
lineShutdown	❌ not applicable (no TAPI application concept)
lineGetDevCaps	❌ not applicable (no TAPI line concept)
lineGetIcon	❌ not applicable (no TAPI line concept)
lineGetID	❌ not applicable (no TAPI line concept)
lineGetLineDevStatus	❌ not applicable (no TAPI line concept)
lineSetLineDevStatus	❌ not applicable (no TAPI line concept)
lineGetDevConfig	❌ not applicable (no TAPI line concept ; the REST API enables to read the configuration)
lineSetDevConfig	❌ not applicable (no TAPI line concept ; the REST API enables to update the configuration)
lineOpen	❌ not applicable (no TAPI line concept)
lineClose	❌ not applicable (no TAPI line concept)
lineNegotiateAPIVersion	❌ not applicable (no TAPI line concept)
lineNegotiateExtVersion	❌ not applicable (no TAPI line concept)
lineGetNumRings	❌ not applicable (no TAPI line concept)
lineSetNumRings	❌ not applicable (no TAPI line concept)
lineGetStatusMessages	❌ not applicable (no TAPI line concept)
lineSetStatusMessages	❌ not applicable (no TAPI line concept)
lineGetAddressCaps	❌ not applicable (no TAPI address concept)
lineGetAddressID	❌ not applicable (no TAPI address concept)
lineGetAddressStatus	❌ not applicable (no TAPI address concept)
lineGetAppPriority	❌ not applicable (no TAPI application handoff concept)
lineSetAppPriority	❌ not applicable (no TAPI application handoff concept)
lineHandoff	❌ not applicable (no TAPI application handoff concept)
lineSetCallPrivilege	❌ not applicable (no TAPI privilege concept)
lineGetNewCalls	❌ not applicable (no TAPI privilege concept)
lineConfigDialog	use the web-based Admin UI: /ngms/admin
lineConfigDialogEdit	use the web-based Admin UI: /ngms/admin
lineConfigProvider	use the web-based Admin UI: /ngms/admin
lineGetTranslateCaps	❌ not supported
lineTranslateAddress	❌ not supported
lineTranslateDialog	❌ not supported
lineGetCountry	❌ not supported
lineRegisterRequestRecipient	❌ not supported
lineSetTollList	❌ not supported
lineSetCurrentLocation	❌ not supported
lineSetCallQualityOfService	❌ not supported
lineSetCallTreatment	❌ not supported
lineSetCallParams	❌ not supported
lineGetRequest	❌ not supported
lineCallbackFunc	use the UCS API WebSocket notifications
lineGetMessage	use the UCS API WebSocket notifications

** : 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.

Requests (TAPI Phone Device Functions)

Messages sent by the Client to NG Media Server.

❌ Phone Device Functions are not supported (to route the audio of a call on the microphone and speaker of a PC, conference a WebRTC call instead)

Responses (TAPI Asynchronous Function Completion)

Communications are based on messages exchanged over networks:

• Requests from the Client (TAPI Functions) can send messages to the network.
• Messages received from the network can deliver notifications (TAPI Callbacks) to the Client.

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

One exception is MakeCall (TAPI lineMakeCall):

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 (TAPI Callbacks)

Messages sent by NG Media Server to the Client.

Event (TAPI)	operationId	Method	Path	Remarks
LINE_APPNEWCALL	onMakeCall	POST	/calls
-	onModifyCall	PATCH	/calls/{id}	{ Op: acceptAck }
LINECALLSTATE_RINGBACK	onModifyCall	PATCH	/calls/{id}	{ Op: accept, State: delivered }
-	onModifyCall	PATCH	/calls/{id}	{ Op: deflectAck }
-	onModifyCall	PATCH	/calls/{id}	{ Op: deflect }
LINECALLSTATE_CONNECTED	onModifyCall	PATCH	/calls/{id}	Incoming call. { Op: answerAck, State: connected }
LINECALLSTATE_CONNECTED	onModifyCall	PATCH	/calls/{id}	Outgoing call. { Op: answer, State: connected }
LINECALLSTATE_DISCONNECTED	onModifyCall	PATCH	/calls/{id}	Cleared localy. { Op: clearAck, State: disconnected, LocalClear: true }
LINECALLSTATE_DISCONNECTED	onModifyCall	PATCH	/calls/{id}	Cleared remotely. { Op: clear, State: disconnected, LocalClear: true }
lineHold succeeded (LINECALLSTATE_ONHOLD)	onModifyCall	PATCH	/calls/{id}	{ Op: holdAck, LocalHold: true }
lineHold failed	onModifyCall	PATCH	/calls/{id}	{ Op: holdRej }
-	onModifyCall	PATCH	/calls/{id}	{ Op: hold, RemoteHold: true }
lineUnhold succeeded (LINECALLSTATE_CONNECTED)	onModifyCall	PATCH	/calls/{id}	{ Op: retrieveAck, LocalHold: false }
lineUnhold failed	onModifyCall	PATCH	/calls/{id}	{ Op: retrieveRej }
-	onModifyCall	PATCH	/calls/{id}	{ Op: retrieve, RemoteHold: false }
lineCompleteTransfer succeeded	onModifyCall	PATCH	/calls/{id}	{ Op: transferAck }
lineCompleteTransfer failed	onModifyCall	PATCH	/calls/{id}	{ Op: transferRej }
lineBlindTransfer succeeded	onModifyCall	PATCH	/calls/{id}	{ Op: singleStepTransferAck }
lineBlindTransfer failed	onModifyCall	PATCH	/calls/{id}	{ Op: singleStepTransferRej }
UPDATE	onModifyCall	PATCH	/calls/{id}	{ Op: transfer }
LINE_MONITORDIGITS	onModifyCall	PATCH	/calls/{id}/detectDigits/{digitId}	{ Digit: ... }
LINE_MONITORTONE	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: ... }
LINECALLSTATE_IDLE	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