Voice Management Guide

The Voice Management user guide

Back to guide

API outbound call and campaign management

This API allows you to manage the calls to be made, either as single outbound calls or as a campaign of outbound calls.
The API allows you to:
1. Request a new outbound call
2. Check the status of an outbound call

1 - General comments

The API operates within a REST paradigm, accepting data as parameters passed through GET or POST and returns data in a JSON format.

1.1 Parameters
All API functions require the use of the following parameters (in addition to the specific parameters):

Name Type Mandatory Description
auth_id
Alphanum 32
Y
API User ID
auth_password
Alphanum 32
Y
Password

1.2 Returned
If successful, the API responds with 200 OK and fields specific to the function named.
In the event of an error, an appropriate HTTP return code is used, and the JSON message will contain the following fields:

Name Type Description
status
Num
HTTP return code
err_code
Alphanum 16
OK if successful, otherwise a specific error code. For example: INVALID_AUTH
err_msg
Alphanum
Error message (readable by a human)

2 - Campaign management

The use of campaigns is optional. It allows for follow-up and the viewing of a set of calls to be made.
The API offers the following functions:
1. Create a new campaign
2. Modify a campaign
3. Check the status of a campaign (statistics)

2.1 Creating a new campaign

URL /vm/campaign
Method(s)
POST
Setting
Name Type Default Mandatory Description
name
Alphanum 32
Y
Name of the campaign to be created
record
Bool
0
N
Enable the recording of all calls for this campaign. Note: even if this value is 0, the recording may be active for other reasons (e.g., configured for an agent)
Returned
Name Type Description
id_campaign
Num
New campaign identifier, to be used for other API calls

2.2 Modifying a campaign

URL /vm/campaign/‹id_campaign›
Method(s)
POST
Settings
Name Type Default Mandatory Description
name
Alphanum 32
N
New campaign name
record
Bool
0
N
Enable the recording of all calls for this campaign. Note: even if this value is 0, the recording may be active for other reasons (e.g. configured for an agent)
pause
Bool
N
Deactivation/activation of the campaign break (unchanged if parameter is absent)
Return
Name Type Description
id_campaign
Num
Campaign ID
name
Alphanum 32
Campaign name
pause
Bool
Indication of campaign break
record
Bool
Indication of activated recording

2.3 Cancelling a campaign

URL /vm/campaign/‹id_campaign›/cancel
Method(s)
POST
Settings

None

Name Type Description
id_campaign
Num
Campaign ID
name
Alphanum 32
Campaign name
pause
Bool
Indication of campaign break
record
Bool
Indication of activated recording

2.4 Checking on the status of a campaign

URL /vm/campaign/‹id_campaign›
Method(s)
GET
Settings

None

Name Type Description
id_campaign
Num
Campaign ID
name
Alphanum 32
Campaign name
pause
Bool
Indication of campaign break
record
Bool
Indication of active recording
total_calls_count
Num 8
Total number of calls to be made
ok_status_count
Num 8
Number of completed calls
ko_status_count
Num 8
Number of failed calls
pending_status_count
Num 8
Number of calls yet to be made

3 - Management of outgoing calls

3.1 Requesting a new outgoing call

URL /vm/outbound_call
Method(s)
POST

Query format
Queries should be made as follows:

				
					curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X POST -d '{"dest_number":<numéro>,"id_agent":<id_agent>}'
Settings
Name Type Default Mandatory Description
id_campaign
Num
N
ID of the campaign the call is part of
type
AUTO/MANUAL
MANUAL
N
Outgoing call type. AUTO: The call is automatically activated as soon as an agent is free. MANUAL: The agent must confirm activation of the call.
id_agent
Num 10
Y/N
The agent who will need to make the call (required if a group is not chosen)
id_group
Num 10
Y/N
The group of agents who will need to make the call (required if an operator is not chosen)
dest_number
Alphanum 1024
Y
One or more recipient numbers depending on whether it’s a campaign or a single outgoing call (in E.164 format without +, separated by commas). Ex: 33170200200,33634123452
priority
Num 3
100
N
Call priority: Default is 100. If lower, this call will have priority. If higher, it will have no priority.
variables
Alphanum 255
N
Variables specific to the call, presented in the popup and usable for statistical monitoring. JSON structure-type format. Ex: {“nom_valeur1”:“valeur1”,“nom_valeur2”:“valeur2”}
ring_timeout
Num 4
30
N
Max ring time, in seconds
retries
Num 4
3
N
Maximum number of callback attempts in case of failure
retry_timeout
Num 4
300
N
(Minimum) time between new attempt, in seconds
auto_timeout
Num 4
0
N
(Minimum) time before the call is automatically activated, in seconds
unassign_timeout
Num 4
60
N
Maximum time for the operator to make the call before allocation to another operator, in seconds
start_from_date
Date/time
Now
N
Start date for making one or more calls, in ISO8601 form. Ex: 2016-11-05T09:00
end_before_date
Date/time
None
N
End date for making one or more calls, in ISO8601 format
start_from_hour
Time
N
(Daily) start time for making one or more calls, in ISO8601 or HH:MM:SS format
end_before_hour
Time
N
(Daily) end time for making one or more calls, in ISO8601 or HH:MM:SS format
Id_msg_op
Num
N
ID of the audio message to be played to the operator

You can assign outgoing calls to an agent in a group if “agent_id” and “group_id” are entered in the same query.

Name Type Description
id_out_call
Num
One or more recipient number IDs, depending on whether it's a campaign or a single outgoing call, separated by commas

3.2 Checking the status of an outgoing call

URL /vm/outbound_call/‹id_out_call›
Method(s)
GET

Parameters
None
Returned
The same fields as those passed when the call was created are returned, with the addition of:

Name Type Description
date_submitted
Date/time
Creation date, in ISO8601 form
alloc_to_id_agent
Num
ID of the agent who made the call
status
PENDING/ASSIGNED/DIALING/CONNECTED/SUCCESS/FAILURE
Call status
call_date
Date/time
Date the call was made (or last attempted), in ISO8601 format
answered_duration
Num
Length of the call (in seconds)
failure_reason
Alphanum 16
Reason for failure
record
URL
Sound resource URL if available and right enabled

3.3 Deleting one or more outgoing calls

URL /vm/outbound_call
Method(s)
DELETE

Only requests in the PENDING state are affected by this method.
Query format
Queries should be made as follows:

				
					

curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X DELETE -d '{"dest_number":<numéro>,"id_agent":<id_agent>}'

Parameters

Name Type Default Mandatory Description
id_campaign
Num
N
Campaign ID the call is part of
type
AUTO/MANUAL
MANUAL
N
Outgoing call type. AUTO: The call is automatically activated as soon as an agent is free. MANUAL: The agent must confirm activation of the call.
dest_number
Alphanum 1024
Y
One or more recipient numbers, depending on whether it's a campaign or a single outgoing call (in E.164 format without +, separated by commas). Ex: 33170200200,33634123452
priority
Num 3
100
N
Call priority: Default is100. If lower, this call will have priority. If higher, it will have no priority.
variables
Alphanum 255
N
Variables specific to the call, presented in the popup and usable for statistical monitoring. JSON structure-type format. Ex: {“nom_valeur1”:“valeur1”,“nom_valeur2”:“valeur2”}
ring_timeout
Num 4
30
N
Maximum ring time, in seconds
retries
Num 4
3
N
Maximum number of callback attempts in case of failure
retry_timeout
Num 4
300
N
(Minimum) time between callbacks, in seconds
auto_timeout
Num 4
0
N
(Minimum) time before the call is automatically activated, in seconds
unassign_timeout
Num 4
60
N
Maximum time for the operator to make the call before allocation to another operator, in seconds
start_from_date
Date/time
Now
N
Start date for making one or more calls, in ISO8601 format. Ex: 2016-11-05T09:00
end_before_date
Date/time
None
N
End date for making one or more calls, in ISO8601 format
start_from_hour
Time
N
(Daily) start time for making one or more calls, in ISO8601 or HH:MM:SS format
end_before_hour
Time
N
(Daily) end time for making one or more calls, in ISO8601 or HH:MM:SS format
id_agent
Num 10
N
The agent who will need to make the call (required if a group is not chosen)
id_group
Num 10
N
The group of agents who will need to make the call (required if an operator is not chosen)

Return
Number of calls impacted.

3.4 Modifying one or more outgoing calls

URL /vm/outbound_call
Method(s)
PUT

Query format
Queries should be made as follows:

				
					curl -u <username>:<password> "https://api.axialys.com/vm/outbound_call" -X PUT -d '{"dest_number":<numéro>,"id_agent":<id_agent>}'

Parameters

Name Type Default Mandatory Description
id_campaign
Num
N
ID for the campaign the call is part of
type
AUTO/MANUAL
MANUAL
N
Outgoing call type. AUTO: The call is automatically activated as soon as an agent is free. MANUAL: The agent must confirm activation of the call.
id_agent
Num 10
Y/N
The agent who will need to make the call (required if a group is not chosen)
id_group
Num 10
Y/N
The group of agents who will need to make the call (required if an operator is not chosen)
dest_number
Alphanum 1024
Y
One or more recipient numbers, depending on whether it’s a campaign or a single outgoing call (in E.164 format without +, separated by commas). Ex: 33170200200,33634123452
priority
Num 3
100
N
Call priority: Default is 100. If lower, this call will have priority If higher, it will have no priority.
variables
Alphanum 255
N
Call-specific variables, presented in the popup and usable for statistical monitoring. JSON structure-type format. Ex: {“nom_valeur1”:“valeur1”,“nom_valeur2”:“valeur2”}
ring_timeout
Num 4
30
N
Maximum ring time, in seconds
retries
Num 4
3
N
Maximum number of callback attempts in case of failure
retry_timeout
Num 4
300
N
(Minimum) time between callbacks, in seconds
auto_timeout
Num 4
60
N
(Minimum) time before the call is automatically activated, in seconds
unassign_timeout
Num 4
60
N
Maximum time for the operator to make the call before allocation to another operator, in seconds
start_from_date
Date/time
Now
N
Start date for making one or more calls, in ISO8601 format. Ex: 2016-11-05T09:00
end_before_date
Date/time
None
N
End date for making one or more calls, in ISO8601 format
start_from_hour
Time
N
(Daily) start time for making one or more calls, in ISO8601 or HH:MM:SS format
end_before_hour
Time
N
(Daily) end time for making one or more calls, in ISO8601 or HH:MM:SS format
Id_msg_op
Num
N
Message ID to be played to the operator

Returned
Number of calls impacted.

  • Table of contents