Skip to main content
ContactNow: Using Agents API Database.php Endpoint for Agent Management
8x8 Support

ContactNow: Using Agents API Database.php Endpoint for Agent Management

Objective

To use API agents to create, read and update agent records, 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
  • Database.php
  • Agent Management

Procedure

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 agents is:

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

The agents 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 uniqueue 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,"account_id":"10278","total":1,"bad":0,"key":0}

Example of XML Response:

<result>
    <success>1</success> 
    <account_id>1234</account_id> 
    <total>1</total>
    <bad>0</bad> 
    <key>0</key>
</result>

Create an Agent Using database.php Endpoint 

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

  • HTTP Request: POST
  • Method: agents
  • Action: create
  • Arguments: raw, format
  • Payload: agentid, name, moh, userfield, filter, pin, username, password, phone, customer, default_status, agent_version, last_broadcast_msg, selfserve_id, aod, aod_lock, audio_id, auth_level, auth_admin, auth_supervisor, auth_reports

POST API call with json: 

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

json Pay Load:

[{"name":"<AGENT_FULLNAME>","moh":"none","userfield":"","filter":"0","pin":"123456","username":"<USERNAME>","password":"<PASSWORD>",
    "phone":"","customer":"0","default_status":"wrap","agent_version":"2","last_broadcast_msg":"","selfserve_id":"<Campaign_ID>",
    "aod":"no","aod_lock":"0","audio_id":"0","auth_level":"admin","auth_admin":"Y","auth_supervisor":"Y","auth_reports":""}]

The Response:

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

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <agent>
        <agentid></agentid>
        <name>AGENT_FULLNAME</name>
        <moh>none</moh>
        <userfield/>
        <filter>0</filter>
        <pin>123456</pin>
        <username>Admin_30203</username>
        <password>PASSWORD</password>
        <phone/>
        <customer>0</customer>
        <default_status>wrap</default_status>
        <agent_version>2</agent_version>
        <last_broadcast_msg/>
        <selfserve_id>0</selfserve_id>
        <aod>no</aod>
        <aod_lock>0</aod_lock>
        <audio_id>0</audio_id>
        <auth_level>admin</auth_level>
        <auth_admin>N</auth_admin>
        <auth_supervisor>N</auth_supervisor>
        <auth_reports/>
    </agent>
</dxi>

The Response:

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

Reading an Agent(s) Using database.php Endpoint 

Read the agent/agents of a campaign/re-seller.

  • HTTP Request: GET
  • Method: agents
  • Action: read
  • Arguments: agentid, name, moh, userfield, filter, pin, username, password, phone, customer, default_status, agent_version, last_broadcast_msg, selfserve_id, aod, aod_lock, audio_id, auth_level, auth_admin, auth_supervisor, auth_reports

Example:

https://api-106.dxi.eu/database.php?token=[Token]&format=json&method=agents&action=read

json Response:

{"success":true,
"total":1,
"list":[
    {"agentid": "550423",
    "name": "Joe Blogs",
    "moh": "none",
    "userfield": "",
    "filter": "0",
    "pin": "123456",
    "username": "Joe",
    "password": "Pa$$w0rd",
    "phone": null,
    "customer": "0",
    "default_status": "wrap",
    "agent_version": "2",
    "last_broadcast_msg": "",
    "selfserve_id": "0",
    "aod": "no",
    "aod_lock": "0",
    "audio_id": "0",
    "auth_level": "admin",
    "auth_admin": "N",
    "auth_supervisor": "N",
    "auth_reports": null}
]}

xml Response:

<?xml version="1.0" encoding="utf-8" ?>
<result>
    <success>1</success>
    <total>1</total>
    <list>
        <agent>
            <agentid>550423</agentid>
            <name>Joe Blogs</name>
            <moh>none</moh>
            <userfield/>
            <filter>0</filter>
            <pin>123456</pin>
            <username>Joe</username>
            <password>Pa$$w0rd</password>
            <phone/>    
            <customer>0</customer>
            <default_status>wrap</default_status>
            <agent_version>2</agent_version>
            <last_broadcast_msg/>
            <selfserve_id>0</selfserve_id>
            <aod>no</aod>
            <aod_lock>0</aod_lock>
            <audio_id>0</audio_id>
            <auth_level>admin</auth_level>
            <auth_admin>N</auth_admin>
            <auth_supervisor>N</auth_supervisor>
            <auth_reports/>
        </agent>
    </list>
</result>

Update an Agent Using database.php Endpoint 

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

  • HTTP Request: POST
  • Method: agents
  • Action: update
  • Arguments: raw, format
  • Payload: agentid, name, moh, userfield, filter, pin, username, password, phone, customer, default_status, agent_version, last_broadcast_msg, selfserve_id, aod, aod_lock, audio_id, auth_level, auth_admin, auth_supervisor, auth_reports

POST API call with json: 

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

json Pay Load:

[{"agentid": "550423","name": "John Dow"}]

The Response:

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

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <agentid>550415</agentid>
    <name>John Dow</name>
</dxi>

The Response:

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

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: