Call notification API
This API allows an external system to be notified about the current calls. The notifications are made of HTTP or HTTPS requests that Accolades will initiate to a web server, triggered by one of the following events:
- a call has been answered (for a call that has this API enabled);
- the server wants to hangup a call and asks for a confirmation or a new duration limit (for a call that has this API enabled);
- a call has been hung up (for a call that has this API enabled).
Enable and configure
This API can be enabled at a user (phone) level, for each user. If you are using the "cloud" service, then you probably do not have access to the configuration interface. In this case you can contact the provider, to enable the API.
The interface for the API management is available in the user info page on the API tab.
For the API to run, the following information must be provided:
- the protocol used for the requests (http or https, probably https);
- the web server where Accolades will send the notifications, as a FQDN (ex: notifications.server.ro) or as an IP;
- the port used for the request (probably 80 for http and 443 for https);
- the path to the file that will process the request (ex: /callNotifications/answer.php).
An incorrect configuration will hang up the call when it is processed by Accolades (for example, if the file that processes the request does not exists).
Notification structure
A notification is sent as a HTTP or HTTP request, to the server stated in the configuration tab.
The data about the call are sent as POST values:
- apiName
- ("callNotification") The name of this API (the parameter can be used to distinguish between the various API systems of the Accolades platform, when the destination server uses the same script to process multiple APIs).
- event
- ("answer", "confirmHangup" or "hangup") The type of event that triggered the notification. Can be "answer" if a call has been answered or "confirmHangup" if the maximum duration for the call has been reached and the server needs to know if the duration is extendes or the call is dropped or "hangup" if a call has been hanged up.
- callId
- (text like numerical.numerical) The unique identifier for the call inside the Accolades system. The value can be used to match different notifications for the same call (the "answer" event and the "hangup" event).
- userId
- (numerical) The unique id of the entity (phone) that triggered the event.
- userType
- ("user") The type of entity that trigger the event (currently this property only has the "user" value - the event was triggered by a phone).
- callDirection
- ("outbound" or "inbound") The call direction relative to the entity that triggered the notification. Can be "inbound" (an incoming call to an Accolades user) or "outbound" (a outgoing call started by an Accolades user).
- callerId
- (text) The phone number of the caller. For calls without a specified caller ID "Anonymus" value will be returned.
- partnerNumber
- (text) The phone number that the Accolades user is connected to (for the outgoing calls, the dialed number and for the incoming call the caller ID of the caller).
- answered
- ("yes" or "no") The call status when the notification was sent. The "yes" value defines a call that was answered, the "no" value is for a call that was not answered. The events of type "answer" will always have this property with the "yes" value because the event is triggered after a call has been answered. The "hangup" type of events can have this property either "yes" (a call that was answered has been hung up) or "no" (a call that was still ringing has been hung up).
- startTime
- (Unix Time) The time that the call has been initiated (for the outgoing calls - the time that the Accolades system started to dial the number, for the incoming calls - the time that the Accolades system sends the call to the Accolades user). This parameter always has a value (it cannot be 0)
- answerTime
- (Unix Time or 0) The time that the call has been answered. If the notification is for a call that has not been answered, then this parameter is set to 0
- hangupTime
- (Unix Time or 0) The time that the call has been terminated. If the notification is for an ongoing call, then this parameter is set to 0.
- hangupCode
- (numeric) Call hangup cause, as a numerical code. A list with the available codes can be found inside the Asterisk manual. For example, code 16 states a normal hangup.
- hangupDescription
- (text) A text description for the hangup cause. A list with the available codes can be found inside the Asterisk manual.
- error
- (text) The parameter is an empty text if no errors were triggered. If an error exists, then this parameter contains the error description.
- errorCode
- (400, 500 or empty text) The error code for the triggered error. If no errors were triggered, then this parameter is empty. Otherwise the 500 value indicates an error inside the Accolades system, 400 indicates an error in the response received by Accolades from the external server.
The values startTime, answerTime and hangupTime are provided using the Unix Time format (the number of second since January 1st, 1970, 00:00:00.
Server response to the request
When an "answer" or "confirmHangup" type notification is sent Accolades will parse the server response. Based on this statement, 3 cases can occur:
- the response has no content (an empty text), so the call will just move forward;
- the response can be parsed as a JSON object, so Accolades will trigger different actions, based on the content of the object;
- Any other case will trigger an error so Accolades will hang up the call and will send an "hangup" event with the error.
Responding to an "answer" event
The JSON answer can have the following parameters:
- confirmHangup
- If the parameter has the "yes" value then Accolades will emit a "confirmHangup" event, after the maximum duration defined below. For any other value, the call will be dropped after the interval has passed;
- callMaxDuration
- The maximum duration for the call (in seconds). After this interval, the call will automatically be terminated. If the parameter is missing, it is 0 or it has a non-numerical value then the call will not be automatically terminated. The maximum allowed value for this parameter is 7200 (2 hours). If a higher value is provided then it will be overwritten with 7200. The minimum allowed value is 30 seconds (if it is not 0). The values between 1 and 30 will be automatically overwritten to 30.
Responding to an "confirmHangup" event
The JSON answer can have the following parameters:
- confirmHangup
- If the parameter has the "yes" value then Accolades will emit a "confirmHangup" event, after the maximum duration defined below. For any other value, the call will be dropped after the interval has passed;
- callMaxDuration
- The maximum duration for the call (in seconds). After this interval, the call will automatically be terminated. If the parameter is missing, it is 0 or it has a non-numerical value then the call will be terminated. The maximum allowed value for this parameter is 7200 (2 hours). If a higher value is provided then it will be overwritten with 7200. The minimum allowed value is 30 seconds (if it is not 0). The values between 1 and 30 will be automatically overwritten to 30.
JSON formatting
Warning! The JSON object must be formatted according to the standard. The keys must be encapsulated in quotes.
Correct format: {"callMaxDuration":"120","confirmHangup":"yes"}.
Incorrect format: {callMaxDuration:"120",confirmHangup:"yes"}.