Check or change the pincode profile parameter of an extension : dbAuthenticate.php

LIMITATION: JSON cannot be used here

Check or update an extension's pincode.

http://sop.ip.address/xml/dbAuthenticate.php

The following parameters are accepted by the URI:

• ext: the extension on which to check or update the pîncode (mandatory)
• password: the extension current pincode. (optional only if existing pincode is empty and command=set)
• command: the type of action to execute. It can be set to "check" to verify an extension's pincode or to "set" to update an extension's pincode. (mandatory)
• newpassword: the extension's new pincode, to be used with "command=set". (optional)
• parameter: the name of the profile parameter that contains the user pincode. If not set, the profile parameter "UserPincode" will be used. (optional).

The URI has the following form:

http://sop.ip.address/xml/dbAuthenticate.php?ext=[extension]&password=[password]&command=[command]&newpassword=[newpassword]&parameter=[parameter]

Examples:

The following call check an extension's pincode stored into the extension profile parameter Pincode.Pincode:

http://sop.ip.address/xml/dbAuthenticate.php?ext=2001&password=1234&command=check&parameter=Pincode.Pincode

If the password provided match the one stored in the database, the return value will be :

<Authenticate><Result>OK</Result></Authenticate>

If the password provided does not match the one in the database or if the profile parameter Pincode.Pincode does not exists or if the extension does not exists, the return value will be:

<Authenticate><Result>NOK</Result></Authenticate>

If the current pincode stored into the database is empty, the return value will be:

<Authenticate><Result>UNDEFINED</Result></Authenticate>

The following call updates an extension's pincode stored into the extension profile parameter Pincode.Pincode:

http://sop.ip.address/xml/dbAuthenticate.php?ext=2001&password=1234&command=set&newpassword=1111&parameter=Pincode.Pincode

Note if there is currently no pincode stored for the extension 2001, any password will be accepted and newpassword will be stored as the new pincode

If the update of the extension's pincode has been successful, the return value will be:

<Authenticate><Result>OK</Result></Authenticate>

If the password provided does not match the one stored in the database, or if the database query failed, or if the profile parameter Pincode.Pincode does not exists for this extension, or if the extension does not exists, the return value will be:

<Authenticate><Result>NOK</Result></Authenticate>

Additional information:

• dbAuthenticate.php will automatically proxy the call to the right SOP in the cluster in case the extension is not the SOP that receive the API call.
• If the command is not correct, the return value will be :

<Authenticate><Error>Bad command XXXXXX</Error></Authenticate>

Return registration information for devices: dbGetRegistration.php

No parameter to set. Returns every device registration on the SOP at once.

<dbGetRegistrationResult>
    <Phones>
        <ID>SDPH0100</ID>
        <IPaddress>-none-</IPaddress>
        <IPport>0</IPport>
        <Registered>0</Registered>
    </Phones>
    <Phones>
        <ID>SDPH0101</ID>
        <IPaddress>172.16.0.1</IPaddress>
        <IPport>5374</IPport>
        <Registered>1</Registered>
    </Phones>

Call Control XML

Initiate a call: ccOriginate

This API function can establish a new call between 2 contacts.

The URI has the following form:

http://sop.ip.address/xml/ccOriginate.php?phone_id=[phone_id]&to=[to]&ext=[ext]&technology=[technology]&async=[true|false]&var=[variables definition]

The following parameters are accepted by the URI:

• phone_id : This SIP phone (if technology isn't set) will be rang first. It can be a phone number if the technology is Local.
• to : If the device in phone_id answers, this number will be rang.
• ext (optional): Can be set in order to specify which caller-id should be shown for the outbound call, it must be an existing extension with PRIMARY or SECONDARY phone defined. If the technology is Local, this parameter is mandatory.
• technology (optional): Can be Local or IAX . This parameter needs to be set if phone_id does not contain a SIP phone resource.
• async (optional): If set to true the function returns as soon as possible, without waiting for the result of the call.
• local_optimization (optional): If set to false the local channel optimization will be disabled. In case technology is Local this will reduce side-effects on channel variables and CDR.
• var (optional): Variables can be set on the channel used to initiate the call. Use the following format: name1=value1|name2=|name3=value3
  Variable names are free. Values are limited to max 59 printable characters in the ranges [0-9], [A-Z] or [a-z].

Note:

• For security reason, the context used will be the context of the phone :
  • if the phone_id is a phone resource, its own context
  • if the phone_id is a phone number, its PRIMARY phone or its SECONDARY if the latter is undefined or not valid (must begin with 'S(D|V)')

The URI returns an XML Object of the form:

<ccOriginateResult>
   <Result>code</Result>
</ccOriginateResult>

Where 'code' is equal to 0 if the ccOriginate action is successful or 1 if there is an error.

Examples:

• http://192.168.11.254/xml/ccOriginate.php?phone_id=SDP40003&to=0026860987
• http://192.168.11.254/xml/ccOriginate.php?phone_id=00496959493&technology=Local&to=0026860987&ext=123456

Hangup an active call: ccHangup

Each active call leg has an identification called the channel id. The Hangup URI lets a 3rd-party application stop an active call based on this channel id.

The URI has the following form:

http://sop.ip.address/xml/ccHangup.php?channel_id=[Channel_id]

where channel_id is the channel returned by the monitoring API (see infra).

The URI returns an XML Object of the form:

<ccHangupResult>
   <Result>code</Result>
</ccHangupResult>

Where 'code' is equal to 0 if the ccHangup action is successful or 1 if there is an error.

Example:

• http://192.168.11.254/xml/ccHangup.php?channel_id=SIP/SDB10001-3a79

Redirect an incoming channel: ccRedirect

The Redirect URI lets a 3rd-party application implement the following workflow:

• The Fusion SOP receives an incoming call.
• The Originating Channel is identified via the evNewOrigChannel event.
• When the URI is called, the incoming call is redirected to a number specified by the 'to' parameter in the URI.
• An optional parameter could be set in order to specify which Caller Id should be shown.

The URI has the following form:

http://sop.ip.address/xml/ccRedirect.php?channel_id=[channel_id]&to=[number]

The URI returns an XML Object of the form:

<ccRedirectResult>
   <Result>code</Result>
</ccRedirectResult>

Where 'code' is equal to 0 if the ccRedirect action is successful or 1 if there is an error.

Example

When receiving an incoming call, we will receive an event of type evNewOrigChannel (see event description chapter), for example:

<evNewOrigChannel>
<Channel>SIP/SDC30015-d156</Channel>
<CallerId>104</CallerId>
<Extension>102</Extension>
</evNewOrigChannel>

This means a call, identified by Originating Channel SIP/SDC30015-d156, from extension 104 is sent to extension 102. After initiating the following URI

http://172.16.35.240/xml/ccRedirect.php?to=9102&channel_id=SIP/SDC30015-d156

the call is redirected from 102 towards 9102.

Place a call on hold: ccHold

http://sop.ip.address>/xml/ccHold.php?channel_id=[channel_id]

To unhold, see chapter Retrieving a channel

This API method is deprecated.

Park a call: ccPark

The ccPark URI lets a 3rd Party application implement the following workflow:

• The Escaux Fusion SOP receives an incoming call
• The Originating Channel is identified via the evNewOrigChannel event
• When the URI is called, the incoming call is redirected to a ParkSlot and the Caller hears Music On Hold.
• An event is generated by the Escaux Fusion SOP to indicate the 3rd-party Application:
  • The ParkSlot number.
  • The Channel which is Parked.
• Optionally, a second channel can be redirected to the park slot as well. This can be usefull when implementing a Barge In function. (as of ccPark v1.2)

The URI has the following form:

http://sop.ip.address/xml/ccPark.php?channel_id=[channel_id]&channel_id2=[channel_id2]

The URI returns an XML Object of the form:

<ccParkResult>
   <Result>code</Result>
</ccParkResult>

Where 'code' is equal to 0 if the ccPark action is successful or 1 if there is an error.

Example

When receiving an incoming call, we will receive an event of type evNewOrigChannel (see event description chapter), for example:

<evNewOrigChannel>
<Channel>SIP/SDC30015-d156</Channel>
<CallerId>104</CallerId>
<Extension>102</Extension>
</evNewOrigChannel>

This means a call, identified by Originating Channel SIP/SDC30015-d156, from extension 104 is sent to extension 102. After initiating the following URI

http://172.16.35.240/xml/ccPark.php?channel_id=SIP/SDC30015-d156

the call is send to a Park Slot (example: 1000) and the following event is generated:

<evParked>
<ParkSlot>1000</ParkSlot>
<Channel>SIP/SDC30015-d156</Channel>
</evParked>

Connecting a channel to a parked channel: ccJoinPark

The ccJoinPark URI lets a 3rd Party application to connect a channel to an already parked channel. As a result the parked channel and the joined channel will be able to communicate.

The URI has the following form:

http://sop.ip.address/xml/ccJoinPark.php?channel_id=[channel_id]&to=[ParkSlot]

• The channel_id is the channel which must be connected to the Parked Call
• The ParkSlot is the slot where the call is parked.

The URI returns an XML Object of the form:

<ccJoinParkResult>
   <Result>code</Result>
</ccJoinParkResult>

Where 'code' is equal to 0 if the ccJoinPark action is successful or 1 if there is an error.

Retrieving a channel

In order to retrieve/take back a channel that has been placed on Hold or that has been parked, the ccRedirect method should be used.

Check the API connection: ccPing

As explained in Chapter 5 "Communication XML events", any third application can connect via TCP/IP on the port 5050 of the Escaux Fusion SOP in order to capture different event types. It might be necessary however to be able to check whether the socket connection to port 5050 is still alive. Therefor the ccPing command can be used.

The URI has the following form:

http://sop.ip.address/xml/ccPing.php

As can be noticed, this URI does not have any parameters. As a result of this ccPing action, two things will happen:

1. the Escaux Fusion SOP will send back an XML response via http
2. the Escaux Fusion SOP will generate an evPong event via the socket connection

The XML response via http takes the following form:

<ccPingResult>
<Result>code</Result>
</ccPingResult>

Where 'code' is equal to 0 if the ccPing action is successful or 1 if there is an error. If the ccPing action is successful, the 3rd party application knows the http API functions are working, but it does not give any information concerning the socket connection. In order to check the socket connection, the 3rd party application should wait for an evPong event. The evPong event is documented in Chapter 5 "Communication XML events". The maximum acceptable delay between sending the ccPing action and receiving the evPong response is 1 second.

Retrieve the list of established channels: ccGetChannels

In order to retrieve all channels:

http://sop.ip.address>/xml/ccGetChannels.php

To retrieve Parked and OnHold channels only, use parameters parked_only or hold_only (modification done in 2.27.4):

http://sop.ip.address/xml/ccGetChannels?parked_only=1

The reply is of the following form:

<Channels>
        <Channel>
                <ID>SIP/SDC30016-97c7</ID>
                <CallerId>"0027884390" [0027884390]</CallerId>
                <Seconds></Seconds>
                <State>Up</State>
                <Link>IAX2/escaux@81.83.50.216:4569/3</Link>
        </Channel>
        <Channel>
                <ID>IAX2/escaux@81.83.50.216:4569/3</ID>
                <CallerId>"0027884390" [0027884390]</CallerId>
                <Seconds>1855</Seconds>
                <State>Up</State>
                <Link>SIP/SDC30016-97c7</Link>
        </Channel>
</Channels>

To retrieve channels and specific variables from the callflow. use parameter show_vars. Each variable need to be separated with the | symbol

http://sop.ip.address/xml/ccGetChannels?show_vars=variable1|variable2|variable3

<Channels>
        <Channel>
                <ID>SIP/SDC30016-97c7</ID>
                <CallerId>"0027884390" [0027884390]</CallerId>
                <Seconds></Seconds>
                <State>Up</State>
                <Link>IAX2/escaux@81.83.50.216:4569/3</Link>
                <Vars>
                   <Variable1>Variable1</Variable1>
                   <Variable2>Variable2</Variable2>
                   <Variable3>Variable3</Variable3>
                </Vars>
        </Channel>
</Channels>

Retrieve the list of queue members: ccGetQueueMembers

Allows to list the members and their state of a particular call queue

http://172.16.35.230/xml/ccGetQueueMembers.php?queue=[queue]&phone=[phone]

• queue (optional): a name of a queue. If omitted, all queues will be queried.
• phone (optional): a name of a resource. e.g. SDPA0001. If omitted, all members will be returned.

Example:

The following API request shows that SDO30001 is a member of the 'GeneralQueue'.

The name and extension of the member (Queue Receptionist - 2000) is available when the member device is assigned as a primary or secondary phone in the internal directory. If the device is the primary or secondary phone for multiple extensions, the name and extension that are returned are picked randomly, depending on which extension was returned first by the database.

The status of the member can be one of the following values:

Status	Meaning
0	Unknown
1	Not in use
2	In use
3	Busy
4	Invalid
5	Unavailable
6	Ringing

The membership of the member can be static (it is a permanent member of the queue) or dynamic (it can be dynamically added or removed) from the queue.

http://172.16.35.230/xml/ccGetQueueMembers.php?queue=GeneralQueue

<Members>
   <Member>
      <Name>Queue Receptionist</Name>
      <Ext>2000</Ext>
      <Phone>SDO30001</Phone>
      <Queue>GeneralQueue</Queue>
      <Status>1</Status>
      <Membership>dynamic</Membership>
      <Paused>0</Paused>
   </Member>
</Members>

Add a phone to a queue: ccQueueAdd

Allows to add a phone to a queue.

http://172.16.35.230/xml/ccQueueAdd.php?queue=[queue]&phone=[phone]

Example:

The following API request adds phone SDP40001 to queue 'GeneralQueue'.

http://172.16.35.230/xml/ccQueueAdd.php?queue=GeneralQueueDemo&phone=SDP40001

<ccQueueAdd>
   <Result>0</Result>
</ccQueueAdd>

API module version 4.2.x and lower does not accept requests to this API function, except if the request originates from the SOP itself. This limitation has been removed starting from API module 4.3.0.

Add a phone to a queue: fusionQueuesSet

Allows to add a phone to a queue.

http://172.16.35.230/xml/fusionQueuesSet.json?queues=[queue]&phone=[phone]"

http://172.16.35.230/xml/fusionQueuesSet.json?queues=ABC&phone=SDX60001"

API module version 5.15.x and lower does not accept requests to this API function.

Remove a phone from a queue: ccQueueRemove

Allows to remove a phone from a queue.

http://172.16.35.230/xml/ccQueueRemove.php?queue=[queue]&phone=[phone]

Example:

The following API request removes phone SDP40001 from queue 'GeneralQueue'.

http://172.16.35.230/xml/ccQueueRemove.php?queue=GeneralQueueDemo&phone=SDP40001

<ccQueueRemove>
   <Result>0</Result>
</ccQueueRemove>

API module version 4.2.x and lower does not accept requests to this API function, except if the request originates from the SOP itself. This limitation has been removed starting from API module 4.3.0.

Remove a phone from a queue:: fusionQueuesRemove

Allows to remove a phone from a queue.

http://172.16.35.230/xml/fusionQueuesRemove.json?queues=[queue]&phone=[phone]"

http://172.16.35.230/xml/fusionQueuesRemove.json?queues=ABC&phone=SDX60001"

API module version 5.15.x and lower does not accept requests to this API function.

Get the number of calls in a queue: ccGetQueueStatus

Allows to check how many callers are waiting in a particular queue.

http://172.16.35.230/xml/ccGetQueueStatus.php?queue=[queue]

Example:

The following API request returns the number of callers in queue 'GeneralQueue'.

http://172.16.35.230/xml/ccGetQueueStatus.php?queue=GeneralQueueDemo

<Queues>
   <Queue>
      <Name>GeneralQueueDemo</Name>
      <Calls>0</Calls>
   </Queue>
</Queues>

Pause a phone inside a given queue: ccQueuePause

Available in API 4.0.0 and later

Allows to put a phone inside a queue in paused or unpaused mode.

http://172.16.35.230/xml/ccQueuePause.php?queue=[queue]&phone=[phone]&paused=[true|false]

Example:

The following API request puts the phone SDX10008 in queue 'GeneralQueueDemo' in paused mode.

http://172.16.35.230/xml/ccQueuePause.php?queue=GeneralQueueDemo&phone=SDX10008&paused=true

<ccQueuePauseResult>
   <Paused>1</Paused>
   <Queue>HuntGroup1</Queue>
</ccQueuePauseResult>

Pause a phone inside all queues: ccQueuePauseAll

Available in API 4.0.0 and later

Allows to put a phone in paused or unpaused mode inside all queues.

http://172.16.35.230/xml/ccQueuePauseAll.php?phone=[phone]&paused=[true|false]

Example:

The following API request puts the phone SDX10008 in paused mode in all queues.

http://172.16.35.230/xml/ccQueuePauseAll.php?phone=SDX10008&paused=true

<PauseAll>
   <Result>1</Result>
</PauseAll>

The status of Result can be one of the following values:

Status	Meaning
0	pause failed
1	pause succeeded
2	unpause failed
3	unpause succeeded

Record a call: ccRecord

Available in API 4.6.0 and higher

Allows to start or stop to record an ongoing call. The call is recorded either on the voicemail of a given user or on the SOP filesystem. If it is recorded on the filesystem, the recorded call is accessible through the File Manager. In this case, it also requires the Call Recording Support module to be installed.

http://172.16.32.21/xml/ccRecord?channel_id=[channel]&mailbox=[extension]&action=[start|stop]&caller_id=[extension]

or

http://172.16.32.21/xml/ccRecord?channel_id=[channel]&filename=[name]&action=[start|stop]&caller_id=[extension]

Call recorded in mailbox 1000 :

http://172.16.32.21/xml/ccRecord?channel_id=SIP/SDO30001-0000003d&mailbox=1000&action=start&caller_id=2000

Call recorded on the filesystem :

http://172.16.32.21/xml/ccRecord?channel_id=SIP/SDO30001-0000003d&filename=exampleFile&action=start&caller_id=2000

You cannot create directory or choose in which directory you save the file. The directory where it will be stored is in the directory RecordedCalls at the root of the file manager.

NOTE : Don't forget that the Call Recording Support module must be installed.

The name of the generated file will be : exampleFile.wav

<ccRecord>
  <Result>0</Result>
</ccRecord>

The status of Result can be one of the following values:

Status	Meaning
0	record succeeded
1	record failed

Set a variable on a call: ccSetVar

Allows to set a variable on an ongoing call.

http://172.16.32.21/xml/ccSetvar?channel_id=[channel]&variable=[variable's name]&value=[variable's value]

0

The status of Result can be one of the following values:

Status	Meaning
0	SetVar succeeded
1	SetVar failed

Get a variable of a call: ccGetVar

Available in API 4.10.0 and higher

Allows to get a variable of an ongoing call.

http://172.16.32.21/xml/ccGetvar?channel_id=[channel]&variable=[variable's name]

test

PUM XML

Requirements

For this feature to work, the computer and the phone must be connected to the network, so the request will be sent to the SOP for a login or logout depending on the user's action. To use the pumLogin or pumLogout API calls, the SOP API module 4.1.10 or >= 4.10.0 and it's dependencies must be installed and activated on the SOP. The time between pumLogin or pumLogout API calls for one extension should be at least 90 seconds. Otherwise, pumLogin and pumLogout will return an error.

Log extension in: pumLogin

Allows to connect a user extension on a given phone, thus performing a PUM login.

Parameters

ext	is the user's extension that should be connected to the physical phone.
phone	is the physical phone where should the extension be connected to.

Response

Result status can be 0 on success and 1 if error occurs following values

If Result is 0, following values are returned
Result	0 for connection has been successfully done
Extension	The extension which has been connected
Phone	The physical phone on which the extension has been connected
Status	The status of the request OK
StatusText	Text describing the success reason
Virtual	The virtual phone which has been connected.
If an error occurs while processing
Result	1 for an error has occurs when processing
Error	The description of the error

Example

The following request connect the virtual phone of the extension 2002 on the physical phone SDP80003.

http://172.16.32.109/xml/pumLogin?ext=2002&phone=SDP80002

<pumLoginResult>
    <Extension>2002</Extension>
    <Phone>SDP80003</Phone>
    <Status>OK</Status>
    <StatusText>Connexion successfully done.</StatusText>
    <Virtual>SVE20001</Virtual>
     <Result>0</Result>
</pumLoginResult>

Log extension out: pumLogout

Allows to disconnect an extension from a phone, thus performing a PUM logout.

Parameters

ext	The user extension that must be disconnected.

Response Result will be 0 if there is no error and 1 otherwise.

If Result is 0, following values are returned
Result	0 for connection has been successfully done
Extension	The extension which has been logged out
Status	The status of the request (OK)
StatusText	Text describing the success reason
If an error occurs while processing
Result	1 for an error has occurs when processing
Error	The description of the error

Example

The following request will remove all virtual phones linked to extension 2002.

http://172.16.32.109/xml/pumLogout?ext=2002

<pumLogoutResult>
    <Extension>2002</Extension>
    <Result>0</Result>
    <Status>OK</Status>
    <StatusText>Logout successfully done.</StatusText>
</pumLogoutResult>