System Configurable Treatment¶

The Configurable Treatments are a resource used, among others, by Communication Barring Profile.

Display system’s configurable treatments¶

GET /api/v1/system/treatments/¶

Retrieve the list of configurable treatments in the system.

Authorization rights: minimum Group Admin.

Example request:

GET /api/v1/system/treatments/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
       "treatments":[
              {
                      "name":"test_treatment",
                      "description":"test description"
              },
              {
                      "name":"test_treatment2",
                      "description":"test description"
              }
       ]
}

Response JSON Object:

treatments (array) – the list of the configurable treatments as defined as treatments attributes.

Status Codes:

200 OK – no error

Add a system’s configurable treatment¶

POST /api/v1/system/treatments/¶

Add a configurable treatment.

Authorization rights: minimum System Admin.

Example request:

POST /api/v1/system/treatments/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
          "treatmentId":"test_treatment2",
          "chargeIndicator":"Charge",
          "description":"test description",
          "accessSIPStatusMessage":"error 400",
          "accessSIPStatusCode":400,
          "networkSIPStatusCode":404,
          "networkSIPStatusMessage":"error 404",
          "q850CauseValue":256,
          "q850Text":"error 256",
          "accessTreatmentAudioFile":"test_accessTreatmentAudioFile",
          "accessTreatmentVideoFile":"test_accessTreatmentVideoFile",
          "networkTreatmentAudioFile":"test_networkTreatmentAudioFile",
          "networkTreatmentVideoFile":"test_networkTreatmentVideoFile",
          "cdrTerminationCause":"8",
          "internalReleaseCause":"Forbidden",
          "accessSendReasonHeader":false,
          "routeAdvance":false,
          "networkSendReasonHeader":false
}

Request JSON Object:

description (string) – (Optional) This field can be used to provide more detail on this treatment and its use.
chargeIndicator (string) – indicates whether a call should be charged. Possible value comes from list: “Charge”, “No Charge”
routeAdvance (boolean) – If this flag is set to true, the route (or contact) processing continues. If this flag is set to false, the call is released immediately.
accessSendReasonHeader (boolean) – This value specifies whether or not a Reason header is added to SIP responses or call terminating requests when releasing a call that was initiated from an access device.
networkSendReasonHeader (boolean) – This value specifies whether or not a Reason header is added to SIP responses or call terminating requests that are sent toward the Network.
accessSIPStatusMessage (string) – it is used when sending the SIP response towards an access device.
accessSIPStatusCode (integer) – it is used when sending the SIP response towards an access device.
networkSIPStatusCode (integer) – This is the status code to use when sending the SIP response toward the network.
networkSIPStatusMessage (string) – This is the message to be appended to the SIP status line when sending the SIP response toward the network.
q850CauseValue (integer) – This value can be defined as a code from 1 to 256. It is sent inside the Reason header if configured to do so. This value should follow the current ISDN.
q850Text (string) – (Optional) a text parameter that can be appended to the Reason header, to explain the Q.850 cause value.
accessTreatmentAudioFile (string) – (Optional) This is the file name of the .wav file to be played to the user when releasing a call that was initiated from an access device
accessTreatmentVideoFile (string) – (Optional) This is the file name of the .mov file to be played to the user before releasing the call (when the call was originated from an access device).
networkTreatmentAudioFile (string) – (Optional) This is the file name of the .wav file to be played to the user before releasing the call.
networkTreatmentVideoFile (string) – (Optional) This is the file name of the .mov file to be played to the user before releasing the call (when the call was originated from the network).
cdrTerminationCause (string) – The call detail record terminationCause is defined as a three-digit string that indicates the reason why the call completed. .
internalReleaseCause (string) – value comes from list: “Busy”,”Forbidden”,”Routing Failure”, “Global FailureRequest Failure”,”Server Failure”,”Translation Failure”,”Temporarily Unavailable”, “User Not Found”,”Request Timeout”,”Dial Tone Timeout”,”Insufficient Credits”

Example response:

HTTP/1.1 201 Created
Content-Type: "application/json"

{}

Status Codes:

201 Created – no error
400 Bad Request – invalid request due to invalid parameters, with possible sub error codes: * 18 INVALID_OPERATION, ‘[Error 8004] Configurable treatment already exists.’.

Display attributes of a configurable treatment¶

GET /api/v1/system/treatments/(string: instance_name)/¶

Retrieve all the attributes of a configurable treatment in the system.

Authorization rights: minimum System Admin.

Example request:

GET /api/v1/system/treatments/treatment_id/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
  "description":"test description",
  "chargeIndicator":"Charge",
  "routeAdvance":false,
  "accessSendReasonHeader":false,
  "networkSendReasonHeader":false,
  "accessSIPStatusCode": 400,
  "accessSIPStatusMessage":"error 400",
  "networkSIPStatusCode":404,
  "networkSIPStatusMessage":"error 404",
  "q850CauseValue":256,
  "q850Text":"error 256",
  "accessTreatmentAudioFile":"test_accessTreatmentAudioFile",
  "accessTreatmentVideoFile":"test_accessTreatmentVideoFile",
  "networkTreatmentAudioFile":"test_networkTreatmentAudioFile",
  "networkTreatmentVideoFile":"test_networkTreatmentVideoFile",
  "cdrTerminationCause":"8",
  "internalReleaseCause": "Busy"
}

Response JSON Object:

description (string) – This field can be used to provide more detail on this treatment and its use.
chargeIndicator (string) – indicates whether a call should be charged. Possible value comes from list: “Charge”, “No Charge”
routeAdvance (boolean) – If this flag is set to true, the route (or contact) processing continues. If this flag is set to false, the call is released immediately.
accessSendReasonHeader (boolean) – This value specifies whether or not a Reason header is added to SIP responses or call terminating requests when releasing a call that was initiated from an access device.
networkSendReasonHeader (boolean) – This value specifies whether or not a Reason header is added to SIP responses or call terminating requests that are sent toward the Network.
accessSIPStatusMessage (string) – it is used when sending the SIP response towards an access device.
accessSIPStatusCode (integer) – it is used when sending the SIP response towards an access device.
networkSIPStatusCode (integer) – This is the status code to use when sending the SIP response toward the network.
networkSIPStatusMessage (string) – This is the message to be appended to the SIP status line when sending the SIP response toward the network.
q850CauseValue (integer) – This value can be defined as a code from 1 to 256. It is sent inside the Reason header if configured to do so. This value should follow the current ISDN.
q850Text (string) – a text parameter that can be appended to the Reason header, to explain the Q.850 cause value.
accessTreatmentAudioFile (string) – This is the file name of the .wav file to be played to the user when releasing a call that was initiated from an access device
accessTreatmentVideoFile (string) – This is the file name of the .mov file to be played to the user before releasing the call (when the call was originated from an access device).
networkTreatmentAudioFile (string) – This is the file name of the .wav file to be played to the user before releasing the call.
networkTreatmentVideoFile (string) – This is the file name of the .mov file to be played to the user before releasing the call (when the call was originated from the network).
cdrTerminationCause (string) – The call detail record terminationCause is defined as a three-digit string that indicates the reason why the call completed. .
internalReleaseCause (string) – value comes from list: “Busy”,”Forbidden”,”Routing Failure”, “Global FailureRequest Failure”,”Server Failure”,”Translation Failure”,”Temporarily Unavailable”, “User Not Found”,”Request Timeout”,”Dial Tone Timeout”,”Insufficient Credits”

Status Codes:

200 OK – no error
404 Not Found – instance not found

Modify a system’s configurable treatment¶

PUT /api/v1/system/treatments/(string: instance_name)/¶

Modify the fields for a configurable treatment.

Authorization rights: minimum System Admin.

Example request:

PUT /api/v1/system/treatments/treatment_id/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
          "treatmentId":"test_treatment2",
          "chargeIndicator":"Charge",
          "description":"test description",
          "accessSIPStatusMessage":"error 400",
          "accessSIPStatusCode":400,
          "networkSIPStatusCode":404,
          "networkSIPStatusMessage":"error 404",
          "q850CauseValue":256,
          "q850Text":"error 256",
          "accessTreatmentAudioFile":"test_accessTreatmentAudioFile",
          "accessTreatmentVideoFile":"test_accessTreatmentVideoFile",
          "networkTreatmentAudioFile":"test_networkTreatmentAudioFile",
          "networkTreatmentVideoFile":"test_networkTreatmentVideoFile",
          "cdrTerminationCause":"8",
          "internalReleaseCause":"Forbidden",
          "accessSendReasonHeader":false,
          "routeAdvance":false,
          "networkSendReasonHeader":false
}

Request JSON Object:

description (string) – (Optional) This field can be used to provide more detail on this treatment and its use.
chargeIndicator (string) – indicates whether a call should be charged. Possible value comes from list: “Charge”, “No Charge”
routeAdvance (boolean) – If this flag is set to true, the route (or contact) processing continues. If this flag is set to false, the call is released immediately.
accessSendReasonHeader (boolean) – This value specifies whether or not a Reason header is added to SIP responses or call terminating requests when releasing a call that was initiated from an access device.
networkSendReasonHeader (boolean) – This value specifies whether or not a Reason header is added to SIP responses or call terminating requests that are sent toward the Network.
accessSIPStatusMessage (string) – (Optional) it is used when sending the SIP response towards an access device.
accessSIPStatusCode (integer) – (Optional) it is used when sending the SIP response towards an access device.
networkSIPStatusCode (integer) – (Optional) This is the status code to use when sending the SIP response toward the network.
networkSIPStatusMessage (string) – (Optional) This is the message to be appended to the SIP status line when sending the SIP response toward the network.
q850CauseValue (integer) – (Optional) This value can be defined as a code from 1 to 256. It is sent inside the Reason header if configured to do so. This value should follow the current ISDN.
q850Text (string) – (Optional) a text parameter that can be appended to the Reason header, to explain the Q.850 cause value.
accessTreatmentAudioFile (string) – (Optional) This is the file name of the .wav file to be played to the user when releasing a call that was initiated from an access device
accessTreatmentVideoFile (string) – (Optional) This is the file name of the .mov file to be played to the user before releasing the call (when the call was originated from an access device).
networkTreatmentAudioFile (string) – (Optional) This is the file name of the .wav file to be played to the user before releasing the call.
networkTreatmentVideoFile (string) – (Optional) This is the file name of the .mov file to be played to the user before releasing the call (when the call was originated from the network).
cdrTerminationCause (string) – (Optional) The call detail record terminationCause is defined as a three-digit string that indicates the reason why the call completed. .
internalReleaseCause (string) – (Optional) value comes from list: “Busy”,”Forbidden”,”Routing Failure”, “Global FailureRequest Failure”,”Server Failure”,”Translation Failure”,”Temporarily Unavailable”, “User Not Found”,”Request Timeout”,”Dial Tone Timeout”,”Insufficient Credits”

Example response:

HTTP/1.1 201 Created
Content-Type: "application/json"

{}

Status Codes:

200 OK – no error
400 Bad Request – invalid request due to invalid parameters
404 Not Found – instance not found

Delete a system’s configurable treatment¶

DELETE /api/v1/system/treatments/(string: instance_name)/¶

Delete a system’s configurable treatment.

Authorization rights: minimum System Admin.

Example request:

DELETE /api/v1/system/treatments/treatment_id/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}

Status Codes:

200 OK – no error. Note that trying to delete a treatment that is not present in the system will not generate an error

Information for configurable treatments¶

One of the more common scenarios where configurable treatments can be put to use is to play different audio (media) announcements for different digit dialing mistakes. Configurable treatments can be also used to replace the audio file played by a service, to send a specific Q.850 value in the Reason header, and to override the terminationCause and charge indicator in the CDRs.

These new audio files (and possibly video) must be recorded for each language supported by the system. These files must be saved in the correct format. For more information on the supported formats, see the “BroadWorks Announcement Guide”. The media files must be placed in the correct directory, under /var/broadworks/Rel_#.#_#.#/sysprompts/[languageId] depending on which release of BroadWorks is currently in use and which languages are supported.

When calling an API for the creation or the modification of configurable treatment is necessary to pass the name of media file already presente on the file system as above.

Unfortunately there is no API available to retrieve the list of existing system announcements, it must be provided by the administrator of the Broadworks platform.

Note

For further information it is possible to refer to the official documentation “BROADWORKS TREATMENT GUIDE”