The Retarus Voice API can be accessed using the SOAP webservice messaging protocol. This SOAP service uses document/literal style binding and can only be used via an encrypted SSL HTTP endpoint-to-endpoint connection. Additional information is available at Web Service Description Language (WSDL).
Webservice URL (WSDL)
https://voice4a.retarus.com/soap/v3?wsdl
Methods
The Webservice offers the following methods to the client application for sending SMS messages:
|
Method name |
Description |
|---|---|
|
getVersionInfo |
Requests the Webservice version |
|
sendJob |
Sends an voice job to the Webservice |
|
getAvailableReports |
Delivers a list of all voice job ids |
|
getJobReport |
Requests available voice job reports |
|
getJobReport |
Requests a status report for a specific voice job |
Authentication & Login IDs
All methods (except getVersionInfo) require authentication with a Login ID and password, i.e., your API user name and password must be the first two parameters in the request object.
Java sample code
// authenticate
final Request request = factory.createJobRequest();
request.setUsername(your_username);
request.setPassword(your_password);
Method getVersionInfo
The webservice’s version identifier can be queried using the getVersionInfo method.
VersionInfoResponse
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
buildNumber |
Revision number |
Integer |
Yes |
|
buildTimestamp |
Date created |
String |
Yes |
|
majorVersion |
First component of the version number, e.g., 2015 |
Integer |
Yes |
|
minorVersion |
Second component of the version number, e.g., 6 |
Integer |
Yes |
|
versionInfo |
Additional information |
String |
Yes |
Java sample code
// send request
final VersionInfoResponse versionInfo = webservice.getVersionInfo();
// print result
System.out.println(String.format("Build: %s / %05d",
versionInfo.getBuildTimestamp(),
Integer.valueOf(versionInfo.getBuildNumber())));
Response
Build: 2014-09-09 11:37:36 +0200/00008
Method sendJob
This method is used to prepare voice jobs to be transferred for processing. If a valid JobRequest has been received by the webservice, it sends an ID back in the JobResponse. This ID must be specified by the client when querying the job status.
JobRequest
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
username |
Retarus Voice API Login ID |
String |
Yes |
|
password |
Retarus Voice API Password |
String |
Yes |
|
contents |
List of contents for the call |
List <Content> |
Yes |
|
recipients |
List of recipients |
List <Recipient> |
Yes |
|
callerId |
The caller ID that should be displayed to the recipient |
String |
Yes |
|
locale |
Language of the contents in order to enable more precise text-to-speech rendering; e.g., “de_DE”, “en_US” |
String |
Yes |
Options
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
jobPeriod |
Time range for transmission (earliest + last): see jobPeriod |
String |
No |
|
blackoutPeriods |
Periods during which jobs are prevented from being sent |
List <String> |
No |
|
costCenter |
Cost center for billing |
String |
No |
|
reference |
Reference |
String |
No |
|
options |
Options (currently only duplicateDetection=true/false supported) |
Map <String,String> |
No |
Content
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
contentType |
Content type (currently only text/plain text supported) |
String |
No |
|
content |
Content interpreted by specified contentType (type + charset) |
Byte |
Yes, or “contentUrl” |
|
contentUrl |
HTTP-lookup address for retrieving content |
String |
Yes, or “content” |
Either “content” or “contentUrl” is required.
A textual content-type should contain a charset. Example: “text/plain; charset=UTF-8”
WAV-content can have the following content-types: “audio/x-wav”, “audio/wav”, “audio/wave”, “audio/vnd.wave”. “audio/x-wav” is recommended.
“Content” or “retrieved content over contentUrl” with content-type “text/plain” can contain placeholders in syntax ${key}. These placeholders are filled with the recipient’s personalization values.
Recipient
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
recipientId |
The destination phone number. |
String |
Yes |
|
callerId |
The caller’s ID that is displayed to the recipient. |
String |
No |
|
blackoutPeriods |
Periods to block transmission. See blackoutPeriod (String) below. |
List<String> |
No |
|
personalization |
Key/value for personalization. |
Map <String,String> |
No |
JobResponse
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
jobId |
Creates the jobId |
String |
Yes |
jobPeriod (String)
|
Type |
Description |
Example |
|---|---|---|
|
start/end |
Start & end timestamp |
2014-08-01T13:00:00Z/2014-08-11T13:00:00Z |
|
start/duration |
Start timestamp + duration |
2014-08- 01T13:00:00Z/P1Y2M10DT2H30M |
|
duration/end |
End timestamp + duration |
2014-08-01T13:00:00Z/P1Y2M10DT2H30M |
|
start |
Earliest start time |
P1Y2M10DT2H30M/2014-08-01T15:30:00Z |
These periods are based on the ISO-standard 8601; for example, Z can be +02:00.
blackoutPeriod (String)
|
Type |
Description |
Example |
|---|---|---|
|
start/end |
Every day between |
10:00Z/11:00Z |
|
start/end |
Start & end timestamp |
2014-08-01T13:00:00Z/2014-08-11T13:00:00Z |
|
start/duration |
Start timestamp + duration |
2014-08-01T13:00:00Z/P1Y2M10DT2H30M |
|
duration/end |
End timestamp - duration |
P1Y2M10DT2H30M/2014-08-01T15:30:00Z |
These periods are based on the ISO-standard 8601; for example, Z can be +02:00.
Java sample code (minimum)
// authenticate
final JobRequest request = factory.createJobRequest();
request.setUsername(your_username);
request.setPassword(your_password);
// Content
final Content content = factory.createContent();
content.setContentType("text/plain; charset=UTF8");
content.setContent("Hello Voice-SOAP-service".getBytes(Charsets.UTF_8));
request.getContents().add(content);
// Recipients
final Recipient recipient = factory.createRecipient();
recipient.setRecipientId("RecipientId.1");
request.getRecipients().add(recipient);
// global
request.setCallerId("GlobalCallerId");
request.setLocale("en_US");
// send to retarus cloud infrastructure
final JobResponse response = webservice.sendJob(request);
// print result
log.info(response.getJobId());
Java sample code (maximum)
// authenticate
final JobRequest request = factory.createJobRequest();
request.setUsername(your_username);
request.setPassword(your_password);
// Content
{
final Content content = factory.createContent();
content.setContentType("text/plain; charset=UTF8");
content.setContent(
"Hello $first name $lastname, this is a call from Voice-SOAP-service"
.getBytes(Charsets.UTF_8));
request.getContents().add(content);
}
{
final Content content = factory.createContent();
content.setContentType("text/plain; charset=UTF8");
content.setContentUrl(http: //host/path/content.txt);
request.getContents().add(content);
}
// Recipients
{
final Recipient recipient = factory.createRecipient();
recipient.setRecipientId("RecipientId.1");
recipient.getBlackoutPeriods().add("00:00/01:00");
recipient.getBlackoutPeriods().add("02:00/03:00");
recipient.getBlackoutPeriods().add("04:00/05:00");
recipient.setCallerId("RecipientCallerId.1");
final Personalization personalization = factory.createPersonalization();
final List<PersonalizationEntry> entries = personalization.getEntries();
{
final.PersonalizationEntry entry = factory.createPersonalizationEntry();
entry.setKey("firstname");
entry.setValue("Max");
entries.add(entry);
}
{
final.PersonalizationEntry entry = factory.createPersonalizationEntry();
entry.setKey("lastname");
entry.setValue("Mustermann");
entries.add(entry);
}
recipient.setPersonalization(personalization);
request.getRecipients().add(recipient)
}
{
final Recipient recipient = factory.createRecipient();
recipient.setRecipientId("RecipientId.2");
recipient.getBlackoutPeriods().add("06:00/07:00");
recipient.getBlackoutPeriods().add("08:00/09:00");
recipient.getBlackoutPeriods().add("10:00/11:00");
recipient.setCallerId("RecipientCallerId.2");
final Personalization personalization = factory.createPersonalization();
final List<PersonalizationEntry> entries = personalization.getEntries();
{
final.PersonalizationEntry entry = factory.createPersonalizationEntry();
entry.setKey("firstname");
entry.setValue("Erika");
entries.add(entry);
}
{
final.PersonalizationEntry entry = factory.createPersonalizationEntry();
entry.setKey("lastname");
entry.setValue("Mustermann");
entries.add(entry);
}
recipient.setPersonalization(personalization);
request.getRecipients().add(recipient)
}
{
final Recipient recipient = factory.createRecipient();
recipient.setRecipientId("RecipientId.3");
recipient.getBlackoutPeriods().add("12:00/13:00");
recipient.getBlackoutPeriods().add("14:00/15:00");
recipient.getBlackoutPeriods().add("16:00/17:00");
recipient.setCallerId(
"RecipientCallerId.3");
// no personalization
request.getRecipients().add(recipient)
}
// global
request.getBlackoutPeriods().add("10:00/11:00");
request.getBlackoutPeriods().add("12:00/13:00");
request.getBlackoutPeriods().add("14:00/15:00");
request.setCallerId("GlobalCallerId");
request.setCostCenter("CostCenter");
request.setLocale("de_DE");
request.setReference("JobReference");
//options
{
final Options options = factory.createOptions();
final List<OptionsEntry> entries = options.getEntries();
final OptionsEntry entry = factory.createOptionsEntry();
entry.setKey("duplicateDetection");
entry.setValue("false");
entries.add(entry);
request.setOptions(options);
}
// send to retarus cloud infrastructure
final JobResponse response = webservice.sendJob(request);
// print result
log.info(response.getJobId());
Response
913af270-a83c-4786-acd0-6b02d63b4670
Method getAvailableJobReports
This method delivers a list of all voice Job IDs.
JobReportRequest
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
username |
Retarus API Login ID |
String |
Yes |
|
password |
Retarus API Password |
String |
Yes |
|
fromTs |
From timestamp in ISO-8601 format (maximum 30 days before toTs, default now – two weeks |
String |
No |
|
toTs |
To timestamp in ISO-8601 format (must be after fromTs), default now |
String |
No |
|
offset |
Offset; default = 0 |
Integer |
No |
|
limit |
Limit response list, default = 100 |
Integer |
No |
|
open |
Whether to return only open or only finished jobs; default = null |
Boolean |
No |
JobReportResponse
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
jobIds |
Job IDs retrieved. |
List <String> |
Yes |
Java sample code (minimum)
// authenticate
final AvailableJobReportsRequest request =
factory.createAvailableJobReportsRequest();
request.setUsername(your_username);
request.setPassword(your_password);
// send request
final AvailableJobReportsResponse availableJobReports =
webservice.getAvailableJobReports(request);
// print result
for (final String id : availableJobReports.getJobIds()) {
log.info(id);
}
Java sample code (maximum)
// authenticate
final AvailableJobReportsRequest request =
factory.createAvailableJobReportsRequest();
request.setUsername(your_username);
request.setPassword(your_password);
// parameter
request.setFromTs("2015-01-16T10:00+02:00");
request.setToTs("2015-01-16T12:00+02:00");
request.setOffset(Integer.valueOf(0));
request.setLimit(Integer.valueOf(100));
request.setOpen(Boolean.TRUE);
// send request
final AvailableJobReportsResponse availableJobReports =
webservice.getAvailableJobReports(request);
// print result
for (final String id : availableJobReports.getJobIds()) {
log.info(id);
}
Response
Job IDs are always listed in ascending order (oldest first):
...
5dc7a915-a27c-461e-8ee4-4b7dfc5aa7c8
4fa823c9-5eb8-44cc-a126-4e0c17e8e2d9
a71afb58-cba8-4a56-a79f-9f7283a3206b
00ba0456-a35f-47c4-8e6c-54bea3edef7e
c0e7f169-f194-42ab-9365-62ccac4c02b6
2711c336-8983-4bc2-85de-57461cd8c21a
78096b5f-8df8-4f90-b05c-61983e68c399
31bb4f74-78e6-4eec-bf60-f694e54597c1
...
Method getJobReport
This method delivers a list of Job IDs from a specific time period. Job IDs up to 6 months old can be retrieved.
JobReportRequest
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
username |
Retarus API Login ID |
String |
Yes |
|
password |
Retarus API Password |
String |
Yes |
|
jobId |
Job ID |
String |
Yes |
JobReportResponse
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
jobId |
Job ID |
String |
Yes |
|
createTs |
From timestamp in ISO-8601 format (maximum 30 days before toTs, default now – two weeks |
String |
Yes |
|
status |
PROCESSING, FINISHED |
String |
Yes |
|
state |
PROCESSING, SUCCESSFUL, PARTIALLY SUCCESSFUL, FAILED |
String |
Yes |
|
reference |
Customer reference |
String |
Default: null |
|
costCenter |
Billing code |
String |
Default: null |
|
recipients |
Recipients of the job |
List <RecipientReport> |
Yes |
RecipientReport
|
Field name |
Description |
Data type |
Required |
|---|---|---|---|
|
recipientId |
Destination phone number. |
String |
Yes |
|
callerId |
Caller phone number. |
String |
Yes |
|
lastTryTs |
Last call attempt in ISO 8601 format. |
String |
Yes |
|
callDuration |
Call duration in seconds (0 if no call attempt has been made). |
double |
Default: null |
|
tryCount |
Retry count (0 if no call attempt has been made). |
int |
Yes |
|
status |
PENDING, SCHEDULED, TRANSMITTING, SUCCESSFUL, FAILED. |
String |
Yes |
|
state |
PROCESSING, FINISHED. |
String |
Yes |
|
statusText |
A status text that can be read by humans. |
String |
Yes |
Java sample code
// authenticate
final JobReportRequest request = factory.createJobRequest();
request.setUsername(your_username);
request.setPassword(your_password);
// jobId
Request.setJobId("2ecfda2b-0161-4eb9-895b-85089b0f777c")
// send to retarus cloud infrastructure
final JobReportResponse response = webservice.getJobReports(request);
// print result
log.info(response);