OZEKI Phone System

HTTP API Notifications

A Notification is a HTTP request sent by the Ozeki Phone System in a HTTP POST request. You can set the phone system to send notifications to given URL addresses. You can also set some of the addresses in command parameters. You can set different URL addresses to different types of notifications. This way it can get an OzML (Ozeki XML) response from the previously set addresses. The OzML response, which is a http response, will then run on the Ozeki Phone System.

If you would like to find out where to set the target URL of a notification, check out this article.

Notifications menu:

  1. Call Routing notification: RoutingInterception
  2. Third Party Call Control notifications:
  3. Api Extension Control notifications:
  4. Error notification

Call Routing notification:

RoutingInterception

Sent when a call routing decision has to be made on incoming calls. Call routing decisions are made before the ringing state and in the ringing state. OzML reponse sent to this request can specify a destination, otherwise the dialplan will be used to route the call. The target URL is set in the HTTP API configuration (Route interception URL).

Parameters:

Name Description
NotificationName Name of the notification request type.
CallerID Displayed ID of the extension who made the call.
OriginalDialedNumber The dialed number which the caller originally called.
LastDialedNumber The dialed number of the last call.
LastCalledExtension The extension which was last called.
LastCallState The last known state of the call when a routing decision need to be made. Call state can be Calling, NoAnswer, Busy, NotFound or Error. Learn more about routing callstates.
CallerExtension Name of the extension who made the call.

Example: 

POST /ozml_example/routing_interception.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 166

NotificationName=RoutingInterception&CallerID=1000&OriginalDialedNumber=1500&
LastDialedNumber=431413&LastCalledExtension=1200&LastCallState=Calling&ApiExtension=9999
Valid commands in the OzML response to this notification:
Route

Third Party Call Control notification:

CallChanged

Sent when a call in the system is created, finished or changes state. The target URL is set in the HTTP API configuration (Call changed URL).

Parameters:

Name Description
NotificationName Name of the notification request type.
CallState Current state of the call. Call state can be Ringing, Hold, Transferred, InCall, Busy, Cancelled, Error or Completed. Read more about callstates.
CallId Call ID of the call.
Caller Extension where the call originates from.
CallerId Caller who initiated the call.
Callee The called extension in this call.

Example: 

POST /ozml_example/call_changed.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 95

NotificationName=CallChanged&CallState=Ringing&CallId=3CiHe&Caller=103&CallerId=103&Callee=101
Valid commands in the OzML response to this notification: AttendedTransfer, BlindTransfer, Forward, Hangup, Hold, Play, Record, SendDTMF, Speak, Unhold

RecordCompleted

Sent when a recording is finished regardless of the success of the recording. It contains a RecordURL parameter which is the path to the recorded file. This notification is sent to the FinishedURL parameter of the HTTP request Record command and the OzML Record command used in HTTP responses.

Parameters:

Name Description
Success Set true if recording was successful. It is false if the call party voice cannot be detected or hung up before anything could be recorded.
Duration If recording was success, the record duration is larger than 0, expressed in seconds.
RecordURL URL of the recorded file. It is empty if recording was not successfull.
CallId Call ID of the call that was recorded.
Caller Caller extension party of the recorded conversation.
Callee Callee extension party of the recorded conversation.
NotificationName Name of the notification request type.

Example: 

POST /ozml_example/record_completed.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 180

Success=true&Duration=15
&RecordURL=http://ozekixepbx.ip:7780/HttpRecordings/21d75202569941b5a9576babd030e55f.mp3
&CallId=3CiHe&Caller=103&Callee=101&NotificationName=RecordCompleted
Valid commands in the OzML response to this notification:
AttendedTransfer, BlindTransfer, Forward, Hangup, Hold, Play, Record, SendDTMF, Speak, Unhold

Api Extension Control notifications:

CallConnected

Sent after a call command issued with an API extension, and when the outgoing call is answered. The target URL can be set in the call command (Url parameter).

Parameters:

Name Description
NotificationName Name of the notification request type.
CallLegID ID of the call between the API extension and another extension.
Callee Extension who answered the call.
ApiExtension ID of the API extension who initiated the call.

Example: 

POST /ozml_example/call_connected.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 76

NotificationName=CallConnected&CallLegID=3CiHe&Callee=1100&ApiExtension=9999
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

IncomingCall

Sent when an extension calls an API extension. The target URL is set in the HTTP API configuration: HTTP API/Notifications/add notifier/Incoming calls /Incoming call URL.

Parameters:

Name Description
NotificationName Name of the notification request type.
CallLegID ID of the ringing call between the API extension and another extension.
Caller Extension who called the API extension.
ApiExtension ID of the API extension which has been called.

Example: 

POST /ozml_example/incoming_call.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 74

NotificationName=IncomingCall&CallLegID=3CiHe&Caller=500&ApiExtension=9998
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

IncomingSMS

Sent when an API extension receives an SMS. This can be achived when the proper dialplan rules are set. The target URL is set in the HTTP API configuration: HTTP API/Notifications/add notifier/Incoming messages/Incoming message URL.

Parameters:

Name Description
NotificationName Name of the notification request type.
Sender SMS source number.
Recipient SMS destination number.
ID ID of this message. It's useful when a delivery notification is received later.
ApiExtension ID of the API extension who received the SMS.
Message Content of the SMS.

Example: 

POST /ozml_example/incoming_sms.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 122

NotificationName=IncomingSMS&Sender=06203123412&Recipient=06304645433&
ID=843952f3-3f3g3&ApiExtension=9999&Message=Hi+John!
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

SMSDeliveryReport

Sent when the system reported that an SMS submitted before with the SendSMS command has reached its destination. The target URL is set in that command (DeliveryReportURL parameter).

Parameters:

Name Description
NotificationName Name of the notification request type.
Delivered If message is delivered, the value is true, false otherwise.
ID ID of the message for which delivery report received.
ApiExtension ID of the API extension who originally sent the SMS.

Example: 

POST /ozml_example/smsdeliveryreport.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 85

NotificationName=SMSDeliveryReport&Delivered=true&ID=843952f3-3f3g3&ApiExtension=9998
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

DtmfEntered

Sent when the other extension sends a DTMF digit or digits while a UserInput command is running and the input digits are not specified as key parameters in the UserInput command . The target URL is set in that command (ForwardToUrl parameter).

Parameters:

Name Description
NotificationName Name of the notification request type.
DtmfDigits DTMF digit or digits sent by the other extension.
CallLegID ID of the API extension call to which the DTMF digits are sent to.
ApiExtension ID of the API extension who received the DTMF digits.

Example: 

POST/ozml_example/dtmf_entered.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 80

NotificationName=DtmfEntered&DtmfDigits=14*5#3&CallLegID=3CiHe&ApiExtension=9998
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

RecordCompleted

Sent when a recording is finished regardless of the success of the recording. It contains a RecordURL parameter which is the path to the recorded file. This notification is sent to the FinishedUrl parameter of the Record command.

Parameters:

Name Description
Success Set true if recording was successful. It is false if the call party voice cannot be detected or hung up before anything could be recorded.
Duration If recording was success, the record duration is larger than 0, expressed in seconds.
RecordURL URL of the recorded file. It is empty if recording was not successfull.
Caller Caller extension party of the recorded conversation.
Callee Callee extension party of the recorded conversation.
NotificationName Name of the notification request type.

Example: 

POST /ozml_example/record_completed.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 169

Success=true&Duration=15
&RecordURL=http://ozekixepbx.ip:7780/HttpRecordings/21d75202569941b5a9576babd030e55f.mp3
&Caller=103&Callee=101&NotificationName=RecordCompleted
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

GoTo

Sent when the GoTo command is called. It is sent to the Url parameter specified in the GoTo command.

Parameters:

Name Description
NotificationName Name of the notification request type.

Example: 

POST /ozml_example/goto.php HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Host: localhost
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 21

NotificationName=GoTo
Valid commands in the OzML response to this notification:
BlindTransfer, Call, Delay, GoTo, Hangup, Play, Record, Reject, SendEmail, SendSms, Speak, UserInput

Error notification:

If an error occurs for example there is an error in the OzML interpretation then a notification will be sent to the error notification URL which can be set in the software. The error notification contains one of the following error codes:
300: ParseError
301: NotImplementedCommand
302: InvalidParameter
303: InappropriateCommand
304: Authentication required
305: Authentication failed
306: Forbidden User
307: ForbiddenAddress
The error notification also sends an error message, read the error messages here.

More information