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

ContactNow: Using tod_policy API Database.php Endpoint for Managing Time of Day Policies

Objective

To use the API tod_policy 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 policies is:

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

The tod_policy 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.

Example of JSON Response:

{"success":true,
"total":1,
"list":[
    {"uid":"2164",
    "description":"MyTOD",
    "default":"queue"}
]}

Example of XML Response:

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

TOD Policy Default Actions to use on API Default Parameter of 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 Policy 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_policy
  • Action: create
  • Arguments: raw, format
  • Payload: description, default

POST API call with json: 

database.php?token=[Token]&format=json&method=tod_policy&action=create&format=[Format]&raw=1

json Pay Load:

[{"description":"OutOfHours","default":"hangup"}]

The Response:

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

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <description>OutOfHours</description>
    <default>hangup</default />
</dxi>

The Response:

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

Reading a TOD Policy Using database.php Endpoint 

Read the data/records of a dataset.

  • HTTP Request: GET
  • Method: tod_policy
  • Action: read
  • Arguments: policy (optional this would be the policy id)

Example:

https://api-106.dxi.eu/database.php?token=[Token]&format=json&method=tod_policy&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 Policy 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_policy
  • Action: update
  • Arguments: raw, format
  • Payload: policy (required - policy id)

POST API call with json: 

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

json Pay Load:

[{"uid":"[Policy_id]","description":"InHours","default":"queue"}]

The Response:

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

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <uid>[Policy_id]</uid>
    <description>InHours</description>
    <default>queue</default>
</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 to the public. Each link will open a new browser tab: