Skip to main content
ContactNow: Using tod_rules API Database.php Endpoint for Managing Time of Day Policy Rules
8x8 Support

ContactNow: Using tod_rules API Database.php Endpoint for Managing Time of Day Policy Rules

Objective

To use the API tod_rules to create, read and update Time of Day rules under a TOD Policy, from outside the standard ContactNow agent or admin interface.

Note: 8x8 does not provide programming support for the ContactNow API. However, further API reference material is linked in the Additional Information section at the bottom of this article.

Applies To

  • ContactNow
  • API
  • Time of Day (TOD)

Procedure(s)

Access the ContactNow API URL  

To access any ContactNow API interface, requests need to have an access token. The token will authorize requests for a particular account for a fixed period of time. By default, these requests are restricted to the internet address that requests the token.

The API url to manage these TOD rules is:

https://api-106.dxi.eu/database.php?token=[Token]&method=tod_rules&action=[Action]&policy=[policy_id]&format=[Format]&raw=1

The tod_rules API has a number of available functions. The request arguments should be passed as HTTP Post or Get variables. The payload / response from the API can be formatted in either json or xml format. The default is json but this can be modified by the format argument below:

  • Formatxml or json

The API will output a number of optional values depending on the request made.

  • Success: This shows whether the request succeeded. It will contain a true or false value for json or a 1 or 0  for xml.
  • Account ID: This shows the authenticated account that ran the API call.
  • Total: Number of records affected.
  • Bad: Number of records that failed.
  • Key: The unique ID that is returned when creating a new record.
  • Error: If the request failed, this field will contain a description of the fault.

It is important to take note of the following pointers when using this API call

  • Both the policy and rule fields are required for all actions. No key_id is returned on import. Not using the policy on action=read will return all rules for all policies.
  • rule: Higher rule numbers are matched first.
  • days: Days are selected using a comma-separated list. e.g. sat,sun to specify the weekend.
  • range: A comma-separated list of time ranges (24h clock). e.g. 09:00-12:00,13:15-17:45
  • action: Available actions - [queue | voicemail | hangup | jump:###]

Example of JSON Response:

{"success":true,
"total":1,
"list":[
    {"policy":"2164",
    "rule":"1",
    "year":"0",
    "month":"0",
    "date":"0",
    "days":"mon,tue,wed,thu,fri",
    "range":"14:0-16:0",
    "action":"queue"}
]}

Example of XML Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<result> 
    <success>1</success> 
    <total>1</total> 
    <list> 
        <tod_rule>
             <policy>2164</policy> 
             <rule>1</rule> 
             <year>0</year> 
             <month>0</month> 
             <date>0</date> 
             <days>mon,tue,wed,thu,fri</days> 
             <range>14:0-16:0</range> 
             <action>queue</action> 
        </tod_rule> 
     </list> 
</result>

TOD Rule Actions to use on API Action Parameter on the Payload 

  • queue - place the call into the queuing system.
  • voicemail - play the queue voicemail message (see audio method) and record the call.
  • hangup - hangup the call.
  • jump:### - send the call to the specified queue id.

Create a TOD Rule Using database.php Endpoint  

This will create a new record and return its success state and a unique key or any errors in the request. If the record already exists it will add a new record with the current details resulting in duplicate records. 

  • HTTP Request: POST
  • Method: tod_rules
  • Action: create
  • Arguments: raw, format
  • Payload: policy, rule, year, month, date, days, range, action 

POST API call with json: 

database.php?token=[Token]&method=tod_rules&action=create&format=[Format]&policy=[policy_id]&raw=1

json Pay Load:

[{"policy":"59809","rule":"1","year":"0","month":"0","date":"0","days":"mon,tue,wed,thu,fri","range":"07:0-16:0","action":"queue"}]

The Response:

{"success":true,"account_id":"10278","total":1,"bad":0,"key":212603}

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <policy>59809</policy>
    <rule>1</rule>
    <year>0</year>
    <month>0</month>
    <date>0</date>
    <days>mon,tue,wed,thu,fri</days>
    <range>07:0-16:0</range>
    <action>queue</action>
</dxi>

The Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
    <total>1</total>
    <bad>0</bad>
    <key>2178</key>

Reading TOD Rules Using database.php Endpoint  

Read the data/records of a dataset.

  • HTTP Request: GET
  • Method: tod_rules
  • Action: read
  • Arguments: policy, rule, year, month, date, days, range, action 

Example:

https://api-106.dxi.eu/database.php?token=[Token]&method=tod_rules&action=read&policy=[policy_id]&raw=1
Note: not using the policy filter will return all TOD's

json Response:

{"success":true,
"total":2,
"list":[
    {"uid":"2164",
    "description":"MyTOD",
    "default":"queue"},
    {"uid":"2178",
    "description":"OutOfHours",
    "default":"hangup"}
]}

xml Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<result>
    <success>1</success>
    <total>2</total>
    <list>
        <tod_policy>
            <uid>2164</uid>
            <description>MyTOD</description>
            <default>queue</default>
        </tod_policy>
        <tod_policy>
            <uid>2178</uid>
            <description>OutOfHours</description>
            <default>hangup</default>
        </tod_policy>
    </list>
</result>

Update a TOD Rule Using database.php Endpoint  

This will update an existing record and return its success state or any errors in the request. 

  • HTTP Request: POST
  • Method: tod_rules
  • Action: update
  • Arguments: raw, format
  • Payload: policy, rule, year, month, date, days, range, action 

POST API call with json: 

database.php?token=[Token]&format=json&method=tod_rules&action=update&raw=1&policy=[Policy_ID]

json Pay Load:

[{"policy":"[Policy_ID]","rule":"[Rule_Number]","year":"0","month":"0","date":"0","days":"mon,tue,wed,thu,fri","range":"07:0-18:0","action":"queue"}]

The Response:

{"success":true,"account_id":"10278","total":1,"bad":0}

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <policy>[Policy_ID]</policy>
    <rule>[Rule_Number]</rule>
    <year>0</year>
    <month>0</month>
    <date>0</date>
    <days>mon,tue,wed,thu,fri</days>
    <range>07:0-18:0</range>
    <action>queue</action>
</dxi>

The Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
    <total>1</total>
    <bad>0</bad>

Additional Information

To create access tokens for the ContactNow API, you will need to create a case with 8x8 Technical Support to obtain an API username and key. Once you have the username and key, you can use the instructions on the following link to create a token for using the API functionality.

The following 8x8 ContactNow API reference material is available: