Skip to main content
Skip table of contents

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);
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.