Voice API - SOAP
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);