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:
Format: xml 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: