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

JAVA

// 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

JAVA

// send request
final VersionInfoResponse versionInfo = webservice.getVersionInfo();

// print result
System.out.println(String.format("Build: %s / %05d",
versionInfo.getBuildTimestamp(),
Integer.valueOf(versionInfo.getBuildNumber())));

Response

CODE

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)

JAVA

// 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)

JAVA

// 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)

CODE

// 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)

JAVA

// 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):

CODE

...
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

JAVA

// 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);