ContactNow: Using Agent.php API Endpoint to Manage Agent Actions

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/agent.php?token=[Token]&action=[Action]&agentid=[agentid]&raw=1

The agent 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}

Example of XML Response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<result> 
    <success>1</success> 
</result>

Agent Actions to Use on API Action Parameter on the API Call 

• agent_dial - This action logs in the agent
• wrap - This action places the agent into idle
• ready - This action places the agent into available
• pause - This action pauses the call recording 
• unpause - This action unpauses the paused call
• hangup - This action hangs up the current call
• hangupready - This action Dispositions the last call
• manual_dial - This action manually dials a record/ddi
• logout - This action Logs out the agent

Log in as an Agent Using the Agent API Endpoint   

This will log an agent in by ringing their phone with the provided argument as their number and return its success state and a unique key or any errors in the request. 

• HTTP Request: POST/GET
• Action: agent_dial
• Arguments: data (Required and this is the number that the agent will be login in from), callerid (optional: number to display on the call)

POST API call with json: 

agent.php?token=[Token]&action=agent_dial&format=[Format]&data=[Agents_number_to call]&raw=1

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Set an Agent Status to Idle Using the Agent API Endpoint   

This places the agent into idle and returns its success state and a unique key or any errors in the request.

• HTTP Request: POST/GET
• Action: wrap
• Arguments: data (optional: provide an idle status code)

POST API call with json: 

agent.php?token=[Token]&action=wrap&format=[Format]&raw=1

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Set an Agent Status to Available Using the Agent API Endpoint

This places the agent into available and returns its success state and a unique key or any errors in the request. 

• HTTP Request: POST/GET
• Action: ready

POST API call with json: 

agent.php?token=[Token]&action=ready&format=[Format]&raw=1

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Manual Dial from an Agent Session Using the Agent API Endpoint

This manually dials a number and return its success state and a unique key or any errors in the request.

• HTTP Request: POST/GET
• Action: manual_dial
• Arguments: data (Required: the number to call), qid (Required: to dial on), callerid (Optional: number to present)

POST API call with json: 

agent.php?token=[Token]&action=manual_dial&format=[Format]&raw=1&data=[DDI]&qid=[Queue_ID]

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Hang up Agent Call Using the Agent API Endpoint

This hangs up the call and places the agent into idle on disposition screen and return its success state and a unique key or any errors in the request.

• HTTP Request: POST/GET
• Action: hangup
• Arguments: data (Optional: disposition code - using this will still provide the agent with the disposition screen)

POST API call with json: 

agent.php?token=[Token]&action=hangup&format=[Format]&raw=1

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Hang up an Agent Call into an Available Status Using the Agent API Endpoint

This hangs up a call and places the agent into available to take the next call it returns its success state and a unique key or any errors in the request. 

• HTTP Request: POST/GET
• Action: hangupready
• Arguments: data (Required: disposition code)

POST API call with json: 

agent.php?token=[Token]&action=hangupready&format=[Format]&raw=1&data=[Disposition_ID]

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Stop a Recording for Agent Call Using the Agent API Endpoint

This stops a recording and returns its success state and a unique key or any errors in the request. 

• HTTP Request: POST/GET
• Action: pause

POST API call with json: 

agent.php?token=[Token]&action=pause&format=[Format]&raw=1

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>

Continue a Stopped Recording for Agent Call Using the Agent API Endpoint 

This continues recording a call and return its success state and a unique key or any errors in the request. 

• HTTP Request: POST/GET
• Action: unpause

POST API call with json: 

agent.php?token=[Token]&action=unpause&format=[Format]&raw=1

The Json Response:

{"success":"true",
"account_id":"10278"}

The XML Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
</result>