API Documentation

WELCORP Web Service API

Overview

The WEL Web Service API allows a registered user to submit a variety of messages and retrieve reports using SOAP over HTTP.

The location of the Web Service, service description and WSDL can be found at
http://www.welcorp.com/webservice/service.asmx

This document is technical in nature and it is assumed that the reader is familiar with SOAP and the implementation of web services.

A note on code samples: These have been provided in .Net c# and Java using callable methods; however, any high-level SOAP toolkit should provide the same functionality. The web service is cross-platform and conforms to the web service standards.

Service Addresses

The original WEL API is located at:
http://www.welcorp.com/webservice/service.asmx

For those who require access to a version using the SOAP DOCUMENT-LITERAL encoding, the address is:
http://www.welcorp.com/webservice/webserviceDL.asmx

Web Methods

Authentication

All web methods require an authentication header consisting of username and password (and optionally user code) to be submitted within the SOAP header.

Authentication Header User Credentials:

PropertyTypeRequiredDescription
UsernameStringYesAssigned username
PasswordStringYesAssigned password
UsercodeStringNoIn the case that the user credentials belong to an administrator, the usercode of the job to be submitted under or retrieved, or of the user to be modified or deleted must be provided.

SubmitJob

This method is used to submit a Fax, Email, SMS, Text to Speech or Voice job to the WEL Corp messaging system.

Expects:
Job entity conforming to one of the following types:- FaxJob, EmailJob, SmsJob, TtsJob or VoiceJob

Returns:
Integer representing the job id or an exception on error.

***Important Note
When sending multiple Fax jobs or multiple Text-to-Speech jobs, there is a non-trivial performance and time cost in converting the document/message, so in the case of multiple identical messages, users are strongly recommended to batch these together into one job, rather than send many individual jobs. This also applies to Voice jobs as uploading multiple large files can also be a performance bottleneck.

Job

Job is an abstract class – submitted jobs must be one of FaxJob, EmailJob, SmsJob, TtsJob or VoiceJob.

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoA future date and time for the job to be activated
RepeatIntervalIntegerNoCauses a scheduled job to repeat every “RepeatInterval” seconds
ListIds[]Integer arrayNo*An array of list id’s if using lists already uploaded to the WEL website.
SenderSenderNoComplex type consisting of sender information.
Recipients[]Recipient arrayNo*Array of message recipients.
AdditionalReportEmailsStringNoList of additional emails to be CC’d on the report email

* One or more ListIds OR one or more Recipient required. Note that you may not use a combination of both ListIds AND Recipient as the object model differs between the two.

FaxJob

Extends Job

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoA future date and time for the job to be activated
RepeatIntervalIntegerNoCauses a scheduled job to repeat every “RepeatInterval” seconds
ListIds[]Integer arrayNo*An array of list id’s if using lists already uploaded to the WEL website.
SenderSenderNoComplex type consisting of sender information.
Files[]FileYesOne or more file objects
Recipients[]FaxRecipient arrayNoRequired if no ListIds submitted. FaxRecipient derives from Recipient
IsHighResBooleanNoIf true, fax is sent in high resolution.
CallbackURLStringNoIf present, a HTML post request will be sent to the specified URL when the system receives a Fax report. Note, this overrides the user setting.
CutOffHourStringNoThe hour that the job will be stopped. (format: 13:00)
DeDupeBooleanNoDedupe the recipient set

EmailJob

Extends Job

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoA future date and time for the job to be activated
RepeatIntervalIntegerNoCauses a scheduled job to repeat every “RepeatInterval” seconds
ListIds[]Integer arrayNo*An array of list id’s if using lists already uploaded to the WEL website.
SenderSenderNoComplex type consisting of sender information.
SubjectStringYesEmail subject
TextStringNo**Text version of email (required if no HTML version exists)
HtmlStringNo**HTML version of email (required if no Text version exists)
Files[]File arrayNoOne or more file objects to be attached to email
Recipients[]EmailRecipient arrayNoRequired if no ListIds submitted. EmailRecipient derives from Recipient
DeDupeBooleanNoDedupe the recipient set

** Either one or both of Text, Html is required

SmsJob

Extends Job
Also sends as MMS if a file is attached.

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoA future date and time for the job to be activated
RepeatIntervalIntegerNoCauses a scheduled job to repeat every “RepeatInterval” seconds
ListIds[]Integer arrayNo*An array of list id’s if using lists already uploaded to the WEL website.
SenderSenderNoComplex type consisting of sender information.
TextStringYesSMS text. Restriction of 3060 characters.
IsTwoWayBooleanYesIs this a two way SMS job?
SMSResponseEmailAddressStringNoEmail address to send the text of the SMS replies to. If blank, the users main email address will be used.
ExpiryHoursByteNoIf this is a two way SMS job, how many hours before job should expire?
BatchRepliesBooleanYesShould replies be batched at expiry? If not, replies will be sent individually to Sender.ReplyTo value as they arrive. For Two Way Jobs only.
Recipients[]SmsRecipient arrayNoRequired if no ListIds submitted. SmsRecipient derives from Recipient
CallbackURLStringNoIf present, a HTML post request will be sent to the specified URL when the system receives a 2 way SMS reply. (Also see below field)
CallbackOnSMSStatusUpdateboolNoIf present, and CallbackURL is set, then callbacks will be made to the specified URL on SMS status updates as well as 2 way SMS replies.
UseTwoWayCustomSenderIDboolNoIf present, and the job is a 2 Way SMS, then the SMS sender id will be the ReplyTo field given in your sender object, and not the WEL automated reply handling numbers. This means WEL will not get replies and optouts. (Not for general use)
CutOffHourStringNoThe hour that sms’s will not be delivered past. NOTE, some carriers will deliver up to an hour after this time, and some carriers might ignore it completely. (format: 13:00)
OptoutCodeStringNoIf a reply to a 2 Way SMS contains this string, then the recipient is added to the users optout list.
DedupeBooleanNoDedupe the recipient set
MMSFileFileNoSend job as MMS if included. Supported file types are:
.gif, .jpg, .jpeg, .mp3, .mp4, .3gpp
LinkInSMSPageStringNoA Page template that will be merged with the recipient fields to create a custom Link In SMS page. See LinkInSMS details below.
LinkInSMSecQuestionStringNoWhen using LinkInSMS, this question must be answered by the recipient before viewing the linked content
LinkInSMSSecAnswerStringNoWhen using LinkInSMS, this answer must be entered by the recipient before viewing the linked content

TtsJob

Extends Job

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoA future date and time for the job to be activated
RepeatIntervalIntegerNoCauses a scheduled job to repeat every “RepeatInterval” seconds
ListIds[]Integer arrayNo*An array of list id’s if using lists already uploaded to the WEL website.
SenderSenderNoComplex type consisting of sender information.
TextStringYesText to speech text.
IsTwoWayBooleanYesIs this a two way TTS job?
KeypressOnlyBooleanYesIf the purpose of your job is to collect keypresses only and not transfer to a third party, set this to true (along with “IsTwoWay”)
SuppressHeaderBooleanYesSuppress the introductory header?
PreferredDestinationTypeEnumNoUseDefault = 0
UseLandline = 1UseMobile = 2
TransferKeys[]
TransferKey array
NoRequired for Two Way TTS jobs (not required where KeypressOnly = true)
KeyAckMessages []KeyAckMessage arrayNoOptional for Two Way TTS jobs.
Recipients[]TtsRecipient arrayNoRequired if no ListIds submitted. TtsRecipient derives from Recipient
VoiceStringNoLanguage/Voice that text will be read in.
HeaderTextStringNoOptional Header Text. Default will be used if blank
SkipMsgRepeatBooleanNoMessage will be repeated unless this field is present and set to “true”
VoiceMailMessageStringNoThe message that will be left if the call is picked up by voicemail.
CutOffHourStringNoThe hour that the job will be stopped. (format: 13:00)
CallbackURLStringNoIf present, a HTML post request will be sent to the specified URL when the system receives a TTS report. Note, this overrides the user setting.
DedupeBooleanNoDedupe the recipient set

VoiceJob

Extends Job

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoA future date and time for the job to be activated
RepeatIntervalIntegerNoCauses a scheduled job to repeat every “RepeatInterval” seconds
ListIds[]Integer arrayNo*An array of list id’s if using lists already uploaded to the WEL website.
SenderSenderNoComplex type consisting of sender information.
RecordingFileYesFile object – only WAV files are accepted.
Recipients[]VoiceRecipient arrayNoRequired if no ListIds submitted. VoiceRecipient derives from Recipient
PreferredDestinationTypeEnumNoUseDefault = 0
UseLandline = 1
UseMobile = 2
TransferKeys[]TransferKey arrayNoRequired for Two Way Voice jobs (not required where KeypressOnly = true)
KeyAckMessages []KeyAckMessage arrayNoOptional for Two Way TTS jobs
IsTwoWayBooleanYesIs this a two way Voice job?
KeypressOnlyBooleanYesIf the purpose of your job is to collect keypresses only and not transfer to a third party, set to true. Note: you must also set IsTwoWay to true for keypresses to be collected
CutOffHourStringNoThe hour that the job will be stopped. (format: 13:00)
CallbackURLStringNoIf present, a HTML post request will be sent to the specified URL when the system receives a Fax report. Note, this overrides the user setting.
DeDupeBooleanNoDedupe the Recipient Set

TtsDirectJob

Extends Job

Properties:

PropertyTypeRequiredDescription
NameStringYesA user defined name for the job
ScheduledDateTimeNoInherited but not used
RepeatIntervalIntegerNoInherited but not used
ListIds[]Integer arrayNo*Inherited but not used
SenderSenderNoInherited but not used
TextStringYesText to speech text.
VoiceStringNoLanguage/Voice that text will be read in.

Sender

Properties:

PropertyTypeRequiredDescription
NameStringNoContact name of user submitting job. If not provided, the company name from the stored user profile will be used.
CompanyStringNo

Company name. If not provided, the company name from the stored user profile will be used.

Company name will be mentioned in TTS broadcasts as part of the introductory message

ReplyToStringNoReply email (for email job) or number/name (for SMS job). If not provided, details in stored user profile will be used. The reply email will be displayed in email broadcasts; the reply mobile number will be displayed in one way SMS jobs.
Note, for SMS jobs, an alphanumeric sender id must be 11 characters or less.

File

Properties:

PropertyTypeRequiredDescription
NameStringYesFile name including extension
PriorityIntegerNoPriority order for multiple files
Content[]Byte arrayYesByte array of file content

Recipient

An abstract class representing a message recipient.

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesDestination – e.g. fax number, email address, phone number or mobile number.

PhoneRecipient

An abstract class representing a phone recipient. Extends Recipient

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesValid phone, fax or mobile number

Valid number construction for Destination:-
Local number with area code e.g. 02 9123 4567
International number with “+” e.g. +44 2 1234 5678
International number with “0011” e.g. 0011 44 2 1234 5678

FaxRecipient

Extends PhoneRecipient.

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesValid phone, fax or mobile number

EmailRecipient

Extends Recipient

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesValid email address
MergeField[]MergeField arrayNoA list of merge key/value pairs

Valid construction for Destination:- any valid email address

SmsRecipient

Extends PhoneRecipient

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesValid phone style number
MergeField[]MergeField arrayNoA list of merge key/value pairs. This can include the LinkInSMS page content. See Link In SMS section.

TtsRecipient

Extends PhoneRecipient

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesValid phone style number
MergeField[]MergeField arrayNoA list of merge key/value pairs

VoiceRecipient

Extends PhoneRecipient

Properties:

PropertyTypeRequiredDescription
ReferenceStringNoUser defined reference for this recipient
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringNoFirst name of recipient
LastNameStringNoLast name of recipient
DestinationStringYesValid email address

MergeField

Properties:

PropertyTypeRequiredDescription
KeyStringYesKey relating to the merge field in message to be replaced.
ValueStringYesValue to replace key with for specific recipient.

TransferKey

Properties:

PropertyTypeRequiredDescription
KeypressByteYesNumber that customer can press.
TransferNumberStringYesPhone number to be transferred to.
MaxSimultaneousCallsIntegerYesMaximum number of simultaneous calls allowed to transfer number.

KeyAckMessage

Properties:

PropertyTypeRequiredDescription
KeypressByteYesNumber that customer can press.
MessageStringYesTTS Message to read out when key is pressed.

RetrieveReport

Use this method to retrieve information about a specific WEL job by Job ID.

Expects:
Integer jobId representing the job to be retrieved.

Returns:
StatusReport entity

RetrieveDetailedReport

Use this method to retrieve a detailed job report by Job ID.

Expects:
Integer jobId representing the job to be retrieved.

Returns:
DetailedReport entity

StatusReport

Entity representing the status report of a job.

Properties:

PropertyTypeDescription
JobIdIntegerThe job id to be retrieved.
JobNameStringThe user assigned Job name
SubmittedDatetimeThe datetime that the job was submitted to the network. This is the system time + System Timezone offset.
JobTypeStringFAX, Email, Voice, SMS, Text-To-Speech
JobStatusStringScheduled, Pending, Broadcast Submitted, Complete, Closed, Queued
TotalRecipientsIntegerTotal number of recipients submitted
SentRecipientsIntegerTotal number successfully sent to
FailedRecipientsIntegerTotal number of failed recipients
TotalCostDoubleTotal cost of job (if complete or closed)
RelatedJobsStringFor repeat scheduled tasks, returns a comma separated string of job IDs that were started by the supplied JobID.
PagesIntegerThe number of Fax pages per recipient sent for fax job, or the number of SMS messages per recipient.
ResentAsStringIf a job has been resent to the failed or errored recipients, this will have the ID of the resend job.
ResendOriginalIDStringIf this job is the resend of a previous job, it will have the id of the original job

DetailedReport

Extends StatusReport

Properties:

PropertyTypeDescription
JobIdIntegerThe job id to be retrieved.
SubmittedDateimeThe datetime that the job was submitted to the network. This is the system time + System Timezone offset.
JobTypeStringFAX, Email, Voice, SMS, Text-To-Speech
JobStatusStringScheduled, Pending, Broadcast Submitted, Complete, Closed, Queued
TotalRecipientsIntegerTotal number of recipients submitted
SentRecipientsIntegerTotal number successfully sent to
FailedRecipientsIntegerTotal number of failed recipients
TotalCostDoubleTotal cost of job (if complete or closed)
RelatedJobsStringFor repeat scheduled tasks, returns a comma separated string of job IDs that were started by the supplied JobID.
PagesIntegerThe number of Fax pages per recipient sent for fax job, or the number of SMS messages per recipient.
ReportRecipient[]ReportRecipient arrayArray of completed recipients for the job

ReportRecipient

Properties:

PropertyTypeDescription
RecipientStringRecipient name
ReferenceStringRecipient reference
DestinationStringFor user lists only:- fax, phone or email
StatusStringSENT, ERR etc.
DurationIntegerFax/TTS/voice jobs only – duration of message
CostDoubleCost of message
KeypressInteger2 Way TTS jobs only – keypress user selected
ReplyString2 Way SMS jobs only – user reply
VoicemailBooleanTrue if the voice message went to Voice Mail

AddUser(User)

Please note: this method is available for administrator and agent privileges only.

Use this method to add users to the broadcast system.

Expects:
User object.

Returns:
Boolean indicating success or fail.

ModifyUser(User)

Please note: this method is available for administrator and agent privileges only.

Use this method to modify users to the broadcast system.

Expects:
User object. You must also provide the usercode of the user to be modified in the authentication header.

Note, only the fields that are not blank or null will be changed.

Returns:
Boolean indicating success or fail.

Note: To update a users password, pass in a user object with all fields blanks except for the new password. Similarly, the other fields can be updated individually.

DeleteUser(User)

Please note: this method is available for administrator and agent privileges only.

Use this method to suspend users from the broadcast system.

Expects:
The usercode of the user to be suspended in the authentication header.

Returns:
Boolean indicating success or fail.

Note: This does not remove the user from the system, but simply sets them to disabled. Alternatively, you can use ModifyUser with user.IsLive = false;
To reactivate a suspended user, user ModifyUser with user.IsLive = true;

User

Entity representing a user object.

Properties:

PropertyTypeRequiredDescription
UserCodeStringYes*User code of the user. This will become the authentication username.
PasswordStringYes*User password
TitleStringNoRecipient title (e.g. Mr, Ms etc)
FirstNameStringYes*First name of recipient
LastNameStringYes*Last name of recipient
EmailStringYes*Email address
PhoneStringNoPhone number
FaxStringNoFax number
MobileStringNoMobile/Cell number
CompanyCompanyYes*Company object (See below)
MonthlyLimitDoubleNoWhat is this user’s monthly spend limit? If not provided this value is set to the system default of 5,000
IsFaxBooleanYes*Activate fax for this user
IsSmsBooleanYes*Activate SMS for this user
IsTtsBooleanYes*Activate TTS for this user
IsEmailBooleanYes*Activate Email for this user
IsTtsTwoWayBooleanYes*Activate 2 way TTS for this user
ReportType **EnumNoDetailed = 0 (default),
Exception = 1,
Summary = 2
ListCosts[]ListCosts arrayNoArray of costs for this user. If not provided, values are set to the reseller default.
CallBackURLStringNoA path for a status update callback. Leave blank for no callback
FaxHeaderTextStringNoAn optional value for the text to go in the Fax header in place of the company name.
IsLiveBooleanNoOn User-Add, a null value will be taken as TRUE.
IsAntiSpamBooleanNoSet to true if the user has agreed to the Anti Spam policy on your system.
EmailToBroadcastEmailAddressStringNoAlternate email to broadcast email address or domain:
Email to Broadcast emails from this address or domain will use this account.
This can be an email address or a domain address.
BroadcastLimitWarnAddressStringNoAlternate email to sent credit/spend limit warnings to
EmailToBroadcastAuthTypeStringNoEmail to broadcast authentication type:
Choose between one of:
– ChResp
– Password
– None
EmailToBroadcastSubjectBehaviourStringNo

How the incoming Email subject is handled:

Choose between one of:
– JobName
– MessageConcat

EmailToBroadcastBodyAsFaxCoverStringNoDoes the email body of an Email to Fax get used as a cover page:
Choose between one of:
– Yes
– No
EmailToBroadcastSignatureStartStringNoText to mark the beginning of the signature area of an Email to broadcast email.
SMSSenderIDStringNoThe default sender ID to use when sending SMS’s.
This must be between 1 and 11 alphanumeric characters only.
DefaultTTSVoiceStringNoThe default voice to use for TTS messages.
This must be one of the voice codes from the “TTS Language Support” section of this document
TTSRepeatCountStringNoThe default number of times to repeat the body of a TTS message.
The text should be one of:
– “Two”
– “Three”
– “Four”
(excluding the quotes)
CreditLimitForAlertStringNoDecimal amount below which a Low Credit alert is sent to the user.
CreditLimitAlertAddressStringNoEmail address to which the low credit alert is sent.
DefaultSMSReplyEmailStringNoDefault email address for SMS replies to be sent to.
EtoBXcodeStringNoCode embedded in the header of an email to broadcast to identify the account used for sending.
HideCostsInReportStringNoOption to hide the final costs in job reports. “Yes” or “No”(default).
SMSFilterOutNonAsciiStringNoFilter out non-ascii characters from outbound SMSs. Value must be “Yes” or “No”(default).
TTSCharLimitStringNoMaximum number of characters that will be sent as a TTS. Extra characters will be discarded.
TTSMsgPrefixStringNoString to be added at the start of all outgoing TTS message. Eg “\Speed=30”
DocRetentionHoursStringNoNumber of hours after which documents are deleted from the server. Leave blank to not delete documents (default)
InboundFaxEmailStringNoEmail address for inbound faxes (if configured) to be emailed to.
ShowRecipientsInOnlineReportStringNoShow recipient details in the online report. “Yes” (default) or “No”.
ShowRecipientsInEmailReportStringNoShow recipient details in the emailed report. “Yes” (default) or “No”.
IncludeCopyOfFaxInReportStringNoOption to include a copy of the sent fax in the emailed fax report. “Yes” or “No”(default).
HideAccountsStringNoDo not display the web portal accounts page to the user. “Yes” or “No”(default).
EmailToBroadcastIPWhiteListStringNoComma separated list of IP addresses allowed to send or relay email to broadcast jobs for the user. Leave blank for no restriction.
EmailToBroadcastIPWhiteListAlertEmailStringNoIf a non-authorized IP address tries to send an email to broadcast job, an alert will be sent to this address if set.
TimeZoneIDStringNoNumeric ID for the users Timezone. See Appendix.

* Required only for the AddUser method. When updating a user, only fields with values will change the user profile.

** Report Types:
Detailed: The user will receive a report listing summary details plus all recipients attempted, success or fail.
Exception: The user will receive a report listing summary details plus recipients who have failed.
Summary: The user will receive a report listing only the basic numbers of total attempted, number successful and number failed.

Company

Entity representing a company object.

Properties:

PropertyTypeRequiredDescription
CompanyNameStringYesCompany name (if not provided, the users name is utilized)
AddressStringNoAddress
CityStringNoCity or suburb
StateStringNo*State if applicable
PostcodeStringNoPost or zip code
CountryStringYesCountry of user. If not provided will be set to the resellers default.

ListCosts

Entity representing a billing object.

Properties:

PropertyTypeRequiredDescription
ListTypeEnumYesAuMedia = 1, (Australian media)
AuBusinesss = 2, (Australian business)
AuGovernment = 4, (Australian government)
Messaging = 3, (User’s own lists, web service lists)
USMedia = 7, (USA media)
AsiaMedia = 8 (Asia Pacific media)
ServiceEnumYesFax = 1,
Email = 2,
SMS = 3,
TextToSpeech = 4,
TextToSpeechMobile = 5,
TwoWaySMS = 9,
TwoWayTTS = 10,
TwoWayTTSMobile = 11
(NOTE, TTS costs also apply to “Voice” calls)
CostDoubleYesCost in dollars. E.g. 0.5 is equivalent to 50 cents
(NOTE, for TTS/Voice, this amount is for Flagfall AND ongoing costs)

AddPrePay(float, string)

Please note: this method is available for administrator privileges only.

Use this method to add a prepayment to a “credit” users account.

Expects:
Float/double: The amount to add to the users credit, eg. 99.99.
String: A payment message for tracking purposes. Eg. “Paid by Visa on 12/12/2020, Auth:ABC123”

Returns:
Boolean indicating success or an error.

Cancel Job

Use this method to cancel unsent scheduled jobs from the WEL system.

Expects:
An Integer containing the Job number of the broadcast to cancel.
In the case of a reoccurring scheduled task, the latest Job number, or the original job number will cancel the scheduled Job.

Returns:
Boolean indicating success or fail.

TtsDirectStatus

Use this method to retrieve the status or associated URL for a TTSDirect Job.

Expects:
Integer jobId representing the job to be retrieved.

Returns:
String containing the job status or a URL to the resulting WAV file.

Using Merge Fields

Merge fields may be used in the following jobs only:-

  1. Email
  2. SMS
  3. Text-To-Speech

To indicate a merge field in your message, the field should be enclosed by double percentage characters – e.g. %%MyField%%

There are reserved merge fields which you may use without specifically creating using the merge key/value pairs. These are:

  1. %%Title%% – recipient’s title
  2. %%FirstName%% – recipient’s first name
  3. %%LastName%% – recipient’s last name
  4. %%Recipient%% – will be replaced by recipient’s full name
  5. %%Reference%% – will be replaced by the recipient’s reference
  6. %%Email%% – will be replaced by the recipient’s destination for Email type jobs
  7. %%Mobile%% – will be replaced by the recipient’s destination for SMS type jobs
  8. %%Phone%% – will be replaced by the recipient’s destination for Text-To-Speech type jobs

Sample message:
Attention: %%Recipient%%

Dear %%FirstName%%,

According to our records you are currently overdue on payment for %%BillName%%. The amount owing is %%BillAmount%%.

Please organize payment before the due date of %%DueDate%%.

Sample Construction

				
					<SmsRecipient>
	<FirstName>Andrew</FirstName>
	<LastName>Citizen</LastName>
	<Reference>19462</Reference>
	<Destination>0412 345 678</Destination>
	<MergeField>
		<Key>BillName</Key>
		<Value>June Electricity Bill</Value>
	</MergeField>
	<MergeField>
		<Key>BillAmount</Key>
		<Value>$78.32</Value>
	</MergeField>
	<MergeField>
		<Key>DueDate</Key>
		<Value>1 August 2007</Value>
	</MergeField>
</SmsRecipient>

				
			

Code Samples

C# Examples

Notes:
The Wel Webservice should be setup as a “Web reference” pointing to http://www.welcorp.com/webservice/service.asmx in your project. Note, in recent versions of Visual studio, this is found under the “Advanced…” button in the “Service Reference” page.

				
					public void TestFax()
{
List<FaxRecipient> recipientList = new List<FaxRecipient>();
FaxRecipient recipient = new FaxRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "02 9123 4567";

recipientList.Add(recipient);

List<File> fileList = new List<File>();

File myFile = new File();
myFile.Name = "test.doc";
myFile.Priority = 1;
System.IO.FileStream file = new System.IO.FileStream("files/test.doc", System.IO.FileMode.Open, System.IO.FileAccess.Read);
System.IO.BinaryReader br = new System.IO.BinaryReader(file);
byte[] buffer = new byte[(int)file.Length];
br.Read(buffer, 0, (int)file.Length);
br.Close();

myFile.Content = buffer;

fileList.Add(myFile);

FaxJob faxJob = new FaxJob();
faxJob.Name = "Test Fax";
faxJob.Sender = new Sender();
faxJob.Sender.Company = "My Company";
faxJob.Sender.Name = "My Name";
faxJob.Sender.ReplyTo = "02 9876 5432";

faxJob.Recipients = recipientList.ToArray();
faxJob.Files = fileList.ToArray();

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(faxJob);

}

public void TestEmail()
{
List<EmailRecipient> recipientList = new List<EmailRecipient>();

EmailRecipient recipient = new EmailRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "a.citizen@theworld.com ";
List<MergeField> fieldList = new List<MergeField>();
MergeField mergeField = new MergeField();
mergeField.Key = "FavouriteAnimal";
mergeField.Value = "Cats";
fieldList.Add(mergeField);

recipient.MergeFields = fieldList.ToArray();

recipientList.Add(recipient);

List<File> myFiles = new List<File>();
File myFile = new File();
myFile.Name = "test.jpg";
myFile.Priority = 1;
System.IO.FileStream file = new System.IO.FileStream("files/test.jpg", System.IO.FileMode.Open, System.IO.FileAccess.Read);
System.IO.BinaryReader br = new System.IO.BinaryReader(file);
byte[] buffer = new byte[(int)file.Length];
br.Read(buffer, 0, (int)file.Length);
br.Close();

myFile.Content = buffer;
myFiles.Add(myFile);

EmailJob emailJob = new EmailJob();
emailJob.Name = "Test Email";
emailJob.Sender = new Sender();
emailJob.Sender.Company = "My Company";
emailJob.Sender.Name = "Test Person";
emailJob.Sender.ReplyTo = "test@test.com";
emailJob.Subject = "My Test Email";
emailJob.Recipients = recipientList.ToArray();
emailJob.Text = "Hi %%FirstName%%, your favourite animal is %%FavouriteAnimal%%.";
emailJob.Files = myFiles.ToArray();

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(emailJob);
}

public void TestSMS()
{
List<SmsRecipient> recipientList = new List<SmsRecipient>();

SmsRecipient recipient = new SmsRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "+61 4 9876 5432";

List<MergeField> fieldList = new List<MergeField>();
MergeField mergeField = new MergeField();
mergeField.Key = "FavouriteAnimal";
mergeField.Value = "Cats";
fieldList.Add(mergeField);

recipient.MergeFields = fieldList.ToArray();
recipientList.Add(recipient);

SmsJob smsJob = new SmsJob();
smsJob.Name = "SMS Test";
smsJob.Sender = new Sender();
smsJob.Sender.Company = "My Company";
smsJob.Sender.Name = "Test Person";
smsJob.Sender.ReplyTo = "+61 4 1234 5678";
smsJob.IsTwoWay = false;
smsJob.Recipients = recipientList.ToArray();
smsJob.Text = "Test SMS message - your favourite animal is %%FavouriteAnimal%%.";

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(smsJob);

}

public void TestTwoWaySMS()
{
List<SmsRecipient> recipientList = new List<SmsRecipient>();

SmsRecipient recipient = new SmsRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "+61 4 9876 5432";

List<MergeField> fieldList = new List<MergeField>();
MergeField mergeField = new MergeField();
mergeField.Key = "FavouriteAnimal";
mergeField.Value = "Cats";
fieldList.Add(mergeField);

recipient.MergeFields = fieldList.ToArray();
recipientList.Add(recipient);

SmsJob smsJob = new SmsJob();
smsJob.Name = "2 Way SMS Test";
smsJob.Sender = new Sender();
smsJob.Sender.Company = "My Company";
smsJob.Sender.Name = "Test Person";
smsJob.Sender.ReplyTo = "smsreplies@mycompany.com";
smsJob.IsTwoWay = true;
smsJob.BatchReplies = false;
smsJob.ExpiryHours = 24;
smsJob.Recipients = recipientList.ToArray();
smsJob.Text = "Test SMS message - your favourite animal is %%FavouriteAnimal%%. Reply to this to get 25% off your next visit to Pet Care.";

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(smsJob);

}

public void TestTTS()
{
List<TtsRecipient> recipientList = new List<TtsRecipient>();

TtsRecipient recipient = new TtsRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "+61 4 9876 5432";

List<MergeField> fieldList = new List<MergeField>();
MergeField mergeField = new MergeField();
mergeField.Key = "FavouriteAnimal";
mergeField.Value = "Cats";
fieldList.Add(mergeField);

recipient.MergeFields = fieldList.ToArray();

recipientList.Add(recipient);

TtsJob ttsJob = new TtsJob();
ttsJob.Name = "Test TTS";
ttsJob.Sender = new Sender();
ttsJob.Sender.Company = "My Company";
ttsJob.Sender.Name = "Test Person";
ttsJob.Sender.ReplyTo = "+61 4 1234 5678";
ttsJob.IsTwoWay = false;

ttsJob.Recipients = recipientList.ToArray();
ttsJob.Text = "Test TTS message - your favourite animal is %%FavouriteAnimal%%.";

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(ttsJob);

}
public void TestTTSTwoWay()
{
List<TtsRecipient> recipientList = new List<TtsRecipient>();

TtsRecipient recipient = new TtsRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "02 9123 4567";

List<MergeField> fieldList = new List<MergeField>();
MergeField mergeField = new MergeField();
mergeField.Key = "FavouriteAnimal";
mergeField.Value = "Cats";
fieldList.Add(mergeField);

recipient.MergeFields = fieldList.ToArray();

recipientList.Add(recipient);

TtsJob ttsJob = new TtsJob();
ttsJob.Name = "Test Two Way TTS";
ttsJob.Sender = new Sender();
ttsJob.Sender.Company = "My Company";
ttsJob.Sender.Name = "Joe Blow";
ttsJob.Sender.ReplyTo = "02 9123 4567";

ttsJob.IsTwoWay = true;
List<TransferKey> transKeys = new List<TransferKey>();
TransferKey transKey = new TransferKey();
transKey.Keypress = 1;
transKey.MaxSimultaneousCalls = 15;
transKey.TransferNumber = "03 9123 4567";
transKeys.Add(transKey);

ttsJob.TransferKeys = transKeys.ToArray();
ttsJob.Recipients = recipientList.ToArray();
ttsJob.Text = "Test TTS message - your favourite animal is %%FavouriteAnimal%%. To speak to a vet, please press 1 now.";

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(ttsJob);

}
public void TestVoice()
{
List<VoiceRecipient> recipientList = new List<VoiceRecipient>();

VoiceRecipient recipient = new VoiceRecipient();
recipient.Title = "Ms";
recipient.FirstName = "Annette";
recipient.LastName = "Citizen";
recipient.Reference = "Of the world";
recipient.Destination = "02 9123 4567";

recipientList.Add(recipient);

File myFile = new File();
myFile.Name = "test.wav";
myFile.Priority = 1;
System.IO.FileStream file = new System.IO.FileStream("files/test.wav", System.IO.FileMode.Open, System.IO.FileAccess.Read);
System.IO.BinaryReader br = new System.IO.BinaryReader(file);
byte[] buffer = new byte[(int)file.Length];
br.Read(buffer, 0, (int)file.Length);
br.Close();

myFile.Content = buffer;

VoiceJob voiceJob = new VoiceJob();
voiceJob.Name = "WAV File Test";
voiceJob.Sender = new Sender();
voiceJob.Sender.Company = "My Company";
voiceJob.Sender.Name = "My Name";

voiceJob.Recipients = recipientList.ToArray();
voiceJob.Recording = myFile;

AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
int jobid = service.SubmitJob(voiceJob);

}

public void GetReport()
{
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
StatusReport statusReport = service.RetrieveReport(1234);
}


public void GetDetailedReport()
{
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
DetailedReport statusReport = service.RetrieveDetailedReport(1234);
}
public void TestAddUser()
{
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "testadmin";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
User user = new User();
user.UserCode = "au/wsnewuser";
user.Title = "Ms";
user.FirstName = "Rita";
user.LastName = "Mae";
user.Email = "rita@somewhere.com";
user.Phone = "03 9123 4567";
user.Mobile = "0412 345 678";
user.Fax = "03 9123 4567";
user.Password = "wsnewuser";
user.ReportType = ReportType.Detailed;
user.IsEmail = true;
user.IsFax = true;
user.IsSms = true;
user.IsTts = false;
user.IsTtsTwoWay = false;

Company company = new Company();
company.CompanyName = "My Company";
company.Address = "1 Green St";
company.City = "Melbourne";
company.State = "VIC";
company.Postcode = "3000";
company.Country = "Australia";

user.Company = company;

List<ListCosts> listCosts = new List<ListCosts>();

ListCosts listCost = new ListCosts();
listCost.ListType = ListType.Messaging;
listCost.Service = Service.Fax;
listCost.Cost = 0.25;
listCosts.Add(listCost);

listCost.ListType = ListType.Messaging;
listCost.Service = Service.SMS;
listCost.Cost = 0.2;
listCosts.Add(listCost);

listCost.ListType = ListType.Messaging;
listCost.Service = Service.Email;
listCost.Cost = 0.1;
listCosts.Add(listCost);

user.ListCosts = listCosts.ToArray();

bool success = service.AddUser(user);
}
public void TestModifyUser()
{
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "testadmin";
authHeader.Password = "test";
authHeader.Usercode = "au/wsnewuser";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
User user = new User();
user.Title = "Ms";
user.FirstName = "Rita";
user.LastName = "Mae";
user.Email = "rita@somewhere.com";
user.Password = "wsnewuser";
user.ReportType = ReportType.Detailed;
user.IsEmail = true;
user.IsFax = true;
user.IsSms = true;
user.IsTts = false;
user.IsTtsTwoWay = false;

Company company = new Company();
company.CompanyName = "My Company";
company.Address = "1 Green St";
company.City = "Melbourne";
company.State = "VIC";
company.Postcode = "3000";
company.Country = "Australia";

user.Company = company;

List<ListCosts> listCosts = new List<ListCosts>();

ListCosts listCost = new ListCosts();
listCost.ListType = ListType.Messaging;
listCost.Service = Service.Fax;
listCost.Cost = 0.25;
listCosts.Add(listCost);

listCost.ListType = ListType.Messaging;
listCost.Service = Service.SMS;
listCost.Cost = 0.2;
listCosts.Add(listCost);

listCost.ListType = ListType.Messaging;
listCost.Service = Service.Email;
listCost.Cost = 0.1;
listCosts.Add(listCost);

user.ListCosts = listCosts.ToArray();

bool success = service.ModifyUser(user);
}
public void TestCancelJob ()
{
AuthenticationHeader authHeader = new AuthenticationHeader();
authHeader.Username = "test";
authHeader.Password = "test";

WelWebService service = new WelWebService();
service.AuthenticationHeaderValue = authHeader;
bool success = service.CancelJob(1234);
}

				
			

Java Axis Examples

Connecting to the Wel Web Service using Java and Axis 1.4

This document assumes that java and axis are setup appropriately, and the user has some basic familiarity with them.

1. Create the Wel Web Service interface classes:

To create the WelService class files and the service Stub run:

java org.apache.axis.wsdl.WSDL2Java (WSDL-file-URL)

as per the axis documentation, then import the resultant classes into your java project.

2. Update Wel Web Service stubs to provide the required Authentication Header.

In the two stub files:

Wel_x0020_Web_x0020_ServiceSoapStub
Wel_x0020_Web_x0020_ServiceSoap12Stub

Insert the below code lines after the statement:

setRequestHeaders(_call);

in the submitJob, retrieveReport and retrieveDetailedReport methods

org.apache.axis.message.SOAPHeaderElement auth = new SOAPHeaderElement("http://www.welcorp.com/webservice/","AuthenticationHeader");
auth.addChildElement("Username","").addTextNode("test");
auth.addChildElement("Password","").addTextNode("test");
_call.addHeader(auth);

3. Main Sample Code

				
					/*
 * Main.java
 *
 * Created on 24 November 2006, 20:51
 *
 */

package weltest;

import com.welcorp.www.webservice.*;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.util.Calendar;
import java.util.LinkedList;
import org.apache.axis.types.UnsignedByte;

public class Main {
    
    public Main() {
    }
    
    public static void main(String[] args) {
        try {
            TestFax();
            //TestEmail();
            //TestSMS();
            //TestTwoWaySMS();
            //testTTS();
            //TestTTSTwoWay();
            //TestVoice();
            //GetReport();
            //GetDetailsReport();
        } catch (Exception e){
            System.err.println(e.toString());
        }
    }
    


    static public void TestFax() throws IOException{
        // Add Fax Recipients
        LinkedList recipientList = new LinkedList();
        FaxRecipient recipient = new FaxRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("02 9123 4567");
        recipientList.add(recipient);
        LinkedList fileList = new LinkedList();
        
        // Add Files to Fax
        File myFile = new File();
        myFile.setName("test.doc");
        myFile.setPriority(1);
        
        java.io.File inFile = new java.io.File("c:/test.doc");
        InputStream is = new FileInputStream(inFile);
        long iFlength = inFile.length();
        byte[] buffer = new byte[(int)iFlength];
        int offset = 0;
        int numRead = 0;
        while (offset < buffer.length && (numRead=is.read(buffer, offset, buffer.length-offset)) >= 0) offset += numRead;
        is.close();
        
        myFile.setContent(buffer);
        fileList.add(myFile);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setCompany("My Company");
        sender.setName("My Name");
        sender.setReplyTo("02 9876 5432");
        
        //Setup FaxJob and add sender, recipients and files
        FaxJob faxJob = new FaxJob();
        faxJob.setName("Test Fax");
        faxJob.setSender(sender);
        faxJob.setRecipients((FaxRecipient[])recipientList.toArray(new FaxRecipient[1]));
        faxJob.setFiles((File[])fileList.toArray(new File[1]));
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        faxJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(faxJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
    }
    

    static public void TestEmail() throws IOException{
        // Add Recipients
        LinkedList recipientList = new LinkedList();
        EmailRecipient recipient = new EmailRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("a.citizen@theworld.com ");
        
        //Create and add merge fields for recipient, then record recipient
        LinkedList fieldList = new LinkedList();
        MergeField mergeField = new MergeField();
        mergeField.setKey("FavouriteAnimal");
        mergeField.setValue("Cats");
        fieldList.add(mergeField);
        recipient.setMergeFields((MergeField[])fieldList.toArray(new MergeField[1]));
        recipientList.add(recipient);
        
        //Add attachment files
        LinkedList fileList = new LinkedList();
        File myFile = new File();
        myFile.setName("test.jpg");
        myFile.setPriority(1);
        
        java.io.File inFile = new java.io.File("c:/test.jpg");
        InputStream is = new FileInputStream(inFile);
        long iFlength = inFile.length();
        byte[] buffer = new byte[(int)iFlength];
        int offset = 0;
        int numRead = 0;
        while (offset < buffer.length && (numRead=is.read(buffer, offset, buffer.length-offset)) >= 0) offset += numRead;
        is.close();
        
        myFile.setContent(buffer);
        fileList.add(myFile);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setName("Test Person");
        sender.setCompany("My Company");
        sender.setReplyTo("test@test.com");
        
        //Setup EmailJob and add sender, recipients and files
        EmailJob emailJob = new EmailJob();
        emailJob.setName("Test Email");
        emailJob.setSender(sender);
        emailJob.setSubject("My Test Email");
        emailJob.setRecipients((EmailRecipient[])recipientList.toArray(new EmailRecipient[1]));
        emailJob.setText("Hi %%FirstName%%, your favourite animal is %%FavouriteAnimal%%.");
        emailJob.setFiles((File[])fileList.toArray(new File[1]));
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        emailJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(emailJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
        
    }
    

    static public void TestSMS(){
        // Add Recipients
        LinkedList recipientList = new LinkedList();
        SmsRecipient recipient = new SmsRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("+61 4 9876 5432");
        
        //Create and add merge fields for recipient, then record recipient
        LinkedList fieldList = new LinkedList();
        MergeField mergeField = new MergeField();
        mergeField.setKey("FavouriteAnimal");
        mergeField.setValue("Cats");
        fieldList.add(mergeField);
        recipient.setMergeFields((MergeField[])fieldList.toArray(new MergeField[1]));
        recipientList.add(recipient);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setName("Test Person");
        sender.setCompany("My Company");
        sender.setReplyTo("+61 4 1234 5678");
        
        //Setup SmsJob and add sender, recipients and files
        SmsJob smsJob = new SmsJob();
        smsJob.setName("SMS Test");
        smsJob.setSender(sender);
        smsJob.setIsTwoWay(false);
        smsJob.setRecipients((SmsRecipient[])recipientList.toArray(new SmsRecipient[1]));
        smsJob.setText("Test SMS message - your favourite animal is %%FavouriteAnimal%%.");
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        smsJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(smsJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
    }
    

    static public void TestTwoWaySMS(){
        // Add Recipients
        LinkedList recipientList = new LinkedList();
        SmsRecipient recipient = new SmsRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("+61 4 9876 5432");
        
        //Create and add merge fields for recipient, then record recipient
        LinkedList fieldList = new LinkedList();
        MergeField mergeField = new MergeField();
        mergeField.setKey("FavouriteAnimal");
        mergeField.setValue("Cats");
        fieldList.add(mergeField);
        recipient.setMergeFields((MergeField[])fieldList.toArray(new MergeField[1]));
        recipientList.add(recipient);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setName("Test Person");
        sender.setCompany("My Company");
        sender.setReplyTo("smsreplies@mycompany.com");
        
        //Setup SmsJob and add sender, recipients and files
        SmsJob smsJob = new SmsJob();
        smsJob.setName("SMS Test");
        smsJob.setSender(sender);
        smsJob.setIsTwoWay(true);
        smsJob.setExpiryHours(new UnsignedByte(24));
        smsJob.setRecipients((SmsRecipient[])recipientList.toArray(new SmsRecipient[1]));
        smsJob.setText("Test SMS message - your favourite animal is %%FavouriteAnimal%%." +
                "Reply to this to get 25% off your next visit to Pet Care.");
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        smsJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(smsJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
    }
    

    static public void testTTS(){
        // Add Recipients
        LinkedList recipientList = new LinkedList();
        TtsRecipient recipient = new TtsRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("+61 4 9876 5432");
        
        //Create and add merge fields for recipient, then record recipient
        LinkedList fieldList = new LinkedList();
        MergeField mergeField = new MergeField();
        mergeField.setKey("FavouriteAnimal");
        mergeField.setValue("Cats");
        fieldList.add(mergeField);
        recipient.setMergeFields((MergeField[])fieldList.toArray(new MergeField[1]));
        recipientList.add(recipient);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setName("Test Person");
        sender.setCompany("My Company");
        sender.setReplyTo("+61 4 1234 5678");
        
        //Setup TTSJob and add sender, recipients and files
        TtsJob ttsJob = new TtsJob();
        ttsJob.setName("TTS Test");
        ttsJob.setSender(sender);
        ttsJob.setIsTwoWay(false);
        ttsJob.setRecipients((TtsRecipient[])recipientList.toArray(new TtsRecipient[1]));
        ttsJob.setText("Test TTS message - your favourite animal is %%FavouriteAnimal%%.");
        ttsJob.setPreferredDestinationType(PreferredDestinationType.UseDefault);
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        ttsJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(ttsJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
    }
    

    static public void TestTTSTwoWay(){
        // Add Recipients
        LinkedList recipientList = new LinkedList();
        TtsRecipient recipient = new TtsRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("02 9123 4567");
        
        //Create and add merge fields for recipient, then record recipient
        LinkedList fieldList = new LinkedList();
        MergeField mergeField = new MergeField();
        mergeField.setKey("FavouriteAnimal");
        mergeField.setValue("Cats");
        fieldList.add(mergeField);
        recipient.setMergeFields((MergeField[])fieldList.toArray(new MergeField[1]));
        recipientList.add(recipient);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setName("Test Person");
        sender.setCompany("My Company");
        sender.setReplyTo("02 9876 5432");
        
        //Setup TransferKeys
        LinkedList transKeys = new LinkedList();
        TransferKey transKey = new TransferKey();
        transKey.setKeypress(new UnsignedByte(1));
        transKey.setMaxSimultaneousCalls(15);
        transKey.setTransferNumber("03 9123 8765");
        transKeys.add(transKey);
        
        //Setup TTSJob and add sender, recipients and files
        TtsJob ttsJob = new TtsJob();
        ttsJob.setName("Test Two Wat TTS");
        ttsJob.setSender(sender);
        ttsJob.setIsTwoWay(true);
        ttsJob.setTransferKeys((TransferKey[])transKeys.toArray(new TransferKey[1]));
        ttsJob.setRecipients((TtsRecipient[])recipientList.toArray(new TtsRecipient[1]));
        ttsJob.setText("Test TTS message - your favourite animal is %%FavouriteAnimal%%. " +
                "your favourite animal is %%FavouriteAnimal%%. To speak to a vet, please press 1 now.");
        ttsJob.setPreferredDestinationType(PreferredDestinationType.UseDefault);
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        ttsJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(ttsJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
    }
    

    static public void TestVoice() throws Exception{
        // Add Recipients
        LinkedList recipientList = new LinkedList();
        VoiceRecipient recipient = new VoiceRecipient();
        recipient.setTitle("Ms");
        recipient.setFirstName("Annette");
        recipient.setLastName("Citizen");
        recipient.setReference("Of the world");
        recipient.setDestination("02 9123 4567");
        recipientList.add(recipient);
        
        // Add Voice File
        File myFile = new File();
        myFile.setName("test.wav");
        myFile.setPriority(1);
        
        // Add Files to Fax
        java.io.File inFile = new java.io.File("c:/test.wav");
        InputStream is = new FileInputStream(inFile);
        long iFlength = inFile.length();
        byte[] buffer = new byte[(int)iFlength];
        int offset = 0;
        int numRead = 0;
        while (offset < buffer.length && (numRead=is.read(buffer, offset, buffer.length-offset)) >= 0) offset += numRead;
        is.close();
        
        myFile.setContent(buffer);
        
        //Set Sender Details
        Sender sender = new Sender();
        sender.setCompany("My Company");
        sender.setName("My Name");
        
        //Setup VoiceJob and add sender, recipients and files
        VoiceJob voiceJob = new VoiceJob();
        voiceJob.setName("WAV File Test");
        voiceJob.setSender(sender);
        voiceJob.setRecipients((VoiceRecipient[])recipientList.toArray(new VoiceRecipient[1]));
        voiceJob.setRecording(myFile);
        voiceJob.setPreferredDestinationType(PreferredDestinationType.UseDefault);
        
        Calendar nextWeek = Calendar.getInstance();
        nextWeek.add(Calendar.DAY_OF_WEEK, 7);
        voiceJob.setScheduled(nextWeek);
        
        try {
            int iret = SendJob(voiceJob);
            System.out.println(iret);
        } catch (Exception e) {
            System.err.println(e.toString());
        }
    }
    

    static public void GetReport() throws Exception{
        
        // Make a service
        Wel_x0020_Web_x0020_Service service = new Wel_x0020_Web_x0020_ServiceLocator();
        // Now use the service to get a stub which implements the SDI.
        Wel_x0020_Web_x0020_ServiceSoap WelWebService = service.getWel_x0020_Web_x0020_ServiceSoap();
        
        StatusReport report = WelWebService.retrieveReport(1234);
        
        System.out.println(report.getJobStatus());
    }
    


    static public void GetDetailsReport() throws Exception{
        // Make a service
        Wel_x0020_Web_x0020_Service service = new Wel_x0020_Web_x0020_ServiceLocator();
        // Now use the service to get a stub which implements the SDI.
        Wel_x0020_Web_x0020_ServiceSoap WelWebService = service.getWel_x0020_Web_x0020_ServiceSoap();
        
        StatusReport report = WelWebService.retrieveDetailedReport(1234);
        
        System.out.println(report.getJobStatus());
        
    }
    


    static public int SendJob(Job oJob) throws Exception{
        // Make a service
        Wel_x0020_Web_x0020_Service service = new Wel_x0020_Web_x0020_ServiceLocator();
        // Now use the service to get a stub which implements the SDI.
        Wel_x0020_Web_x0020_ServiceSoap WelWebService = service.getWel_x0020_Web_x0020_ServiceSoap();
        
        int iRes = WelWebService.submitJob(oJob);
        
        return iRes;
    }
}


    static public void CancelJob () throws Exception{
        // Make a service
        Wel_x0020_Web_x0020_Service service = new Wel_x0020_Web_x0020_ServiceLocator();
        // Now use the service to get a stub which implements the SDI.
        Wel_x0020_Web_x0020_ServiceSoap WelWebService = service.getWel_x0020_Web_x0020_ServiceSoap();
        
        Boolean success = WelWebService.canceljob(1234);
        
        System.out.println(success);
        
    }

				
			

PHP Code Example

Connecting to the Wel Web Service using PHP and NuSoap

This document assumes that PHP is installed and configured, and the newsoap library is downloaded and installed.

Change ‘./nusoap/lib/nusoap.php’ to match the location of your nusoap library.

Basic SMSJob example:

				
					<html><body>
<?php
	require_once('./nusoap/lib/nusoap.php');  

	$namespace = "http://www.welcorp.com/webservice/";

	//Setup Header
	$hdrArr = array(
		'Username' => 'test',
		'Usercode' => 'test',
		'Password' => 'test');

	//Create properly typed header object
	$hdr = array('AuthenticationHeader' => new soapval('AuthenticationHeader', 'AuthenticationHeader', $hdrArr, false, $namespace));

	//Setup Job parameters
	$jobarr = array(
		'Name' => 'Test Job name',
		'Sender' => array(
			'ReplyTo' => '098765432'
		),
		'Recipients' => array(
			'Recip_1' => array(
				'Destination' => '+098765432', 
				'Reference' => 'testing'
			)
		),
		'Text' => 'Test message goes here.',
		'IsTwoWay' => false,
		'BatchReplies' => false,
		'ExpiryHours' => new soapval('ExpiryHours', 'unsignedByte', 0, false, 'http://www.w3.org/2001/XMLSchema')  //Need this soapval, otherwise it goes out as an int, not an unsignedbyte
	);

	//Create properly typed job object
	$smsJob = array(new soapval('job', 'SmsJob', $jobarr, false, $namespace));

	//create client and get wsdl
	$client = new nusoap_client('http://www.welcorp.com/webservice/service.asmx?WSDL', 'wsdl');

	$err = $client->getError();
	if ($err) echo '<h2>Constructor error</h2><pre>' . $err . '</pre>';

	//Do call
	$result = $client->call('SubmitJob', $smsJob, $namespace, false, $hdr);
	
	// Display the result
	print_r($result);
	// Display the request and response
	echo '<h2>Request</h2>';
	echo '<pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>';
	echo '<h2>Response</h2>';
	echo '<pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>';

?>
</body></html>
				
			

Basic FAXJob example:

				
					<html><body>
<?php
	require_once('nusoap.php');

	$namespace = "http://www.welcorp.com/webservice/";

	//setup Header
	$hdrArr = array(
		'Username' => 'test',
		'Password' => 'test');
	//create properly typed header object
	$hdr = array('AuthenticationHeader' => new soapval('AuthenticationHeader', 'AuthenticationHeader', $hdrArr, false,$namespace));
	
	//setup job parameters
	// Open File
	$file = "test.pdf";
	if( !($fp = fopen($file, "r")))
	{
	// Error opening file
	// Handle error as appropriate for your script
	exit;
	}
	 
	// Read data from the file into $data
	$data = "";
	while (!feof($fp)) $data .= fread($fp,1024);

	
	$filearr = array("Test.pdf", false, base64_encode($data));
	
	
	$jobarr = array(
		'Name' => 'test api',
		'Sender' => array(
			'ReplyTo' => '+18178008516'
		),
		'Recipients' => array(
			'Recip_1' => array(
				'Destination' => '+33957029251',
				'Reference' => 'testAPI'
			)
		),
		'Files' => array(new soapval('TestFile', 'File', array($filearr), false, $namespace),
		'ExpiryHours' => new soapval('ExpiryHours', 'unsignedByte', 0, false, 'http://www.w3.org/2001/XMLSchema') 	//Need this soapval, otherwise it goes out as an int, not an unsigned byte
	);


	//create properly typed job object
	$smsJob = array(new soapval('job', 'FaxJob', $jobarr, false, $namespace));

	//create client and get wsdl
	$client = new nusoap_client('http://www.welcorp.com/webservice/service.asmx?WSDL', 'wsdl');

	$err = $client->getError();
	if ($err) echo '<h2>Construction error</h2><pre>' . $err . '</pre>';

	//Do call

	$result = $client->call('SubmitJob', $smsJob, $namespace, false, $hdr);

	//Display Result
	print_r($result);

	//Display the request and response
	echo '<h2>Request</h2>';
	echo '<pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>';
	echo '<h2>Response</h2>';
	echo '<pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>';
	?>
	</body>
</html>
				
			

Add User example:

				
					<html><body>
<?php
	require_once('nusoap.php');  

	$namespace = "http://www.welcorp.com/webservice/"; 

	//Setup Header 
	$hdrArr = array( 
		'Username' => 'agent_or_admin_username', 
		'Password' => 'agent_or_admin_password');
		
	//Create properly typed header object 
	$hdr = array('AuthenticationHeader' => new soapval('AuthenticationHeader', 'AuthenticationHeader', $hdrArr, false, $namespace)); 
	
	//Setup User 
	$userarr = array(
	'UserCode' => 'au/apiuseraddtest2',
	'Password' => 'Testing123',
	'FirstName' => 'FN-APITest2',
	'LastName' => 'LN-APITest2',
	'Email' => 'apitest2@test.com',
	'IsFax' => false,
	'IsSms' => false,
	'IsTts' => false,
	'IsEmail' => true,
	'IsTtsTwoWay' => false);

	//create properly typed user object
	$userobj = array(new soapval('newuser', 'User', $userarr, false, $namespace));
	
	//create client and get wsdl
	$client = new nusoap_client('http://www.welcorp.com/webservice/service.asmx?WSDL', 'wsdl');

	$err = $client->getError(); 
	if ($err) echo '<h2>Constructor error</h2><pre>' . $err . '</pre>';	
	
	//Do call	
	$result = $client->call('AddUser', $userobj, $namespace, false, $hdr);
	
	// Display the result
	print_r($result);
	
	// Display the request and response
	echo '<h2>Request</h2>';
	echo '<pre>' . htmlspecialchars($client->request, ENT_QUOTES) . '</pre>';
	echo '<h2>Response</h2>';
	echo '<pre>' . htmlspecialchars($client->response, ENT_QUOTES) . '</pre>';

?>
	</body>
</html>
				
			

Appendix

Valid number formats

Valid phone, fax or mobile number construction:-

Local number with area codee.g. 02 9123 4567
International number with “+”e.g. +44 2 1234 5678
International number with “0011”e.g. 0011 44 2 1234 5678

Other number constructions are invalid.

Broadcast Status Codes

List CreatedUser has created their job, but has not yet submitted it.
PendingFor SMS only:- job is in the pending queue.
RetryFor SMS only:- aggregator cannot be contacted, job has been re-queued.
Queued By WSFor Web Service submissions only:- job has been queued and awaiting processing.
Test SentFor Fax and TTS only:- user has requested a test send and is awaiting results.
ScheduledJob is scheduled for later date and time.
Broadcast SubmittedJob has been submitted and is currently in progress.
CompleteJob is complete.
ClosedJob has been closed (either completed or cancelled).
CancelledScheduled job has been cancelled by user.

SMS Message Lengths

1 messageUp to 160 characters.
2+ messages153 characters per SMS message.
(so 400 characters would take 3 messages)

Current maximum is 3060 characters, for a 20 part SMS message

Send Codes

SENTMessage was successfully sent to the recipient.

Fax Specific Error Codes

BUSYLine gave busy signal with all retries. The receiving fax machine was busy.
NOANPhone keeps ringing. Nobody answers. If you are sure that the number is correct, please contact the recipient. There may be a problem with their fax machine (e.g. out of paper).
INVDThe number is not a valid number. Please check the number and dial again.
NOLNProblem with phone line. Please check line.
BARRWrong number (number changed, call barred).
NSUPService or Function not supported by network or user.
COLLAt the moment we started trying to send a fax a call came in.
ERRProcedural or unknown error.
FAILDocument conversion failed. Please resubmit your document.
NOFXNo fax machine detected. Please check the number and try again.
PAGCNo confirmation received after last page transmitted. The fax may have been received by the recipient and the machine failed to confirm.
BADCBad connection or fax modem error at receiving end.
OPTONumber in users optoutlist
REFUCall refused by recipient or carrier

Text-To-Speech Specific Error Codes

BUSYLine busy.
BSINIncorrect number
NOANPhone keeps ringing. Nobody answers.
MGNCReceipt of message not confirmed.
OPTONumber in users optoutlist
REFUCall refused by recipient or carrier
ERRProcedural or unknown error
LDTELatest Delivery timeout expired
NOLNProblem with phone line. Please check line.
HNUPCall disconnected by the network or remote user (reason unspecified).
RJCTThe message has been rejected

SMS Specific Error Codes

DERRAggregator error.
UERRUser validation error.
TRANTransaction limit reached.
PERRInvalid password.
SVRESMS server error – please retry later.
SNDEError in sender number.
RECEError in receiver number.
MSGENo SMS message.
LENESMS message too long.
NUMESending number invalid.
OUTESMS outgoing update error.

Notes:
For SMS: Status SENT indicates that the message has been successfully submitted to the network. In some cases the message may fail after if the number does not exist or for some other network related issue. In these cases, the status will be updated accordingly up to four hours after submission.

For Email: All emails are submitted and the system must wait to either receive bounced back emails, or to receive notification that an email has been read. The system cannot ascertain if all emails are read – if a recipient uses an HTML email package and does not block outgoing code then the “Read” status will be received. However, this is a minority of recipients. After 12 hours the job is closed and all emails that have not failed are updated to “Sent”.

TTS Language Support.

The valid values for the TTSJob.Voice parameter are:

Voice CodeComment
English-Allison (default)American English, female.
English-AlanAustralian English, male
English-GraceAustralian English, female
English-DaveAmerican English, male
English-StevenAmerican English, male
English-SusanAmerican English, female
English-KateBritish English, female
English-SimonBritish English, male
Chinese-LinlinChinese, female
Chinese-LishengChinese, female
French-JulietteFrench, female
French-CharlotteCanadian French, female
French-OlivierCanadian French, male
Italian-LucaItalian, male
German-KatrinGerman, female
Mexican-EsperanzaMexican, female
Portuguese-GabrielaBrazilian Portuguese, female
Portuguese-FelipeBrazilian Portuguese, male
Portuguese-FernandaBrazilian Portuguese, female
Spanish-CarlosAmerican Spanish, male
Spanish-DiegoArgentine Spanish, male
Spanish-FranciscaChilean Spanish, female
Spanish-SoledadAmerican Spanish, female

These values are case insensitive.

Timezone Numeric codes

Used in the User object to set the users timezone.

Albania +1 GMT1
Algeria +1 GMT2
American Samoa -11 GMT195
Andorra +1 GMT3
Angola +1 GMT4
Anguilla -4 GMT5
Antarctica -2 GMT6
Antigua And Barbuda -4 GMT7
Argentina -3 GMT8
Argentina – Western Province -4 GMT9
Armenia +4 GMT10
Aruba -4 GMT11
Ascension Island0 GMT12
Australia – AEST +10 GMT14
Australia – Lord Howe Island +10.5 GMT13
Australia – Northern Territory +9.5 GMT15
Australia – Queensland +10 GMT16
Australia – South Australia +9.5 GMT17
Australia – Western Australia +8 GMT18
Austria +1 GMT19
Azerbaijan +3 GMT263
Bahamas -5 GMT21
Bahrain +3 GMT22
Bangladesh +6 GMT23
Barbados -4 GMT24
Belarus +2 GMT25
Belgium +1 GMT26
Belize -6 GMT27
Benin +1 GMT28
Bermuda -4 GMT29
Bhutan +6 GMT30
Bolivia -4 GMT31
Botswana +2 GMT32
Brazil – Acre -5 GMT33
Brazil – Atlantic Islands -2 GMT34
Brazil – East -3 GMT35
Brazil – West -4 GMT36
Brunei +8 GMT38
Bulgaria +2 GMT39
Burkina Faso0 GMT40
Burundi +2 GMT41
Cambodia +7 GMT42
Cameroon +1 GMT43
Canada – Atlantic -4 GMT44
Canada – Central -6 GMT45
Canada – Eastern -5 GMT46
Canada – Mountain -7 GMT47
Canada – Newfoundland -3.5 GMT48
Canada – Yukon & Pacific -8 GMT49
Cayman Islands -5 GMT52
Chad +1 GMT53
Chile -4 GMT56
China +8 GMT57
Colombia -5 GMT58
Cook Islands -10 GMT60
Costa Rica -6 GMT61
Croatia +1 GMT62
Cuba -5 GMT63
Cyprus +2 GMT64
Czech Republic +1 GMT65
Denmark +1 GMT66
Djibouti +3 GMT67
Dominica -4 GMT68
Ecuador -5 GMT70
Egypt +2 GMT71
El Salvador -6 GMT72
Equatorial Guinea +1 GMT73
Eritrea +3 GMT74
Estonia +2 GMT75
Ethiopia +3 GMT76
Falkland Islands -4 GMT77
Fiji +12 GMT78
Finland +2 GMT79
France +1 GMT80
French Guiana -3 GMT81
French Polynesia -10 GMT82
Gabon +1 GMT83
Gambia0 GMT84
Georgia +4 GMT85
Germany +1 GMT86
Ghana0 GMT87
Greece +2 GMT88
Greenland -3 GMT89
Greenland – Scoresbysun -1 GMT90
Greenland – Thule -4 GMT91
Grenada -4 GMT92
Guadeloupe -4 GMT93
Guam +10 GMT94
Guatemala -6 GMT95
Guyana -3 GMT97
Haiti -5 GMT98
Honduras -6 GMT99
Hong Kong +8 GMT100
Hungary +1 GMT101
Iceland0 GMT102
India +5.5 GMT103
Indonesia – Central +8 GMT104
Indonesia – East +9 GMT105
Indonesia – West +7 GMT106
Iran +3.5 GMT107
Iraq +3 GMT108
Ireland0 GMT109
Israel +2 GMT110
Italy +1 GMT111
Ivory Coast0 GMT112
Jamaica -5 GMT113
Japan +9 GMT114
Jordan +2 GMT115
Kazakhstan +6 GMT116
Kenya +3 GMT117
Kiribati +12 GMT118
Kuwait +3 GMT121
Kyrgyzstan +5 GMT122
Laos +7 GMT123
Latvia +2 GMT124
Lebanon +2 GMT125
Lesotho +2 GMT126
Liberia0 GMT127
Libya +2 GMT128
Lithuania +2 GMT129
Luxembourg +1 GMT130
Macedonia +1 GMT131
Madagascar +3 GMT132
Malawi +2 GMT134
Malaysia +8 GMT135
Maldives +5 GMT136
Mali0 GMT137
Malta +1 GMT138
Mariana Island +10 GMT165
Marshall Islands +12 GMT140
Martinique -4 GMT141
Mauritania0 GMT142
Mauritius +4 GMT143
Mayotte +3 GMT144
Mexico -6 GMT145
Mexico – Baja Calif Norte -8 GMT146
Mexico – Nayarit Sinaloa Sonora -7 GMT147
Moldova +2 GMT148
Monaco +1 GMT149
Mongolia +8 GMT150
Morocco0 GMT151
Mozambique +2 GMT152
Namibia +1 GMT153
Nepal +5.75 GMT155
Netherlands +1 GMT156
New Caledonia +11 GMT158
New Zealand +12 GMT159
Nicaragua -6 GMT160
Niger +1 GMT161
Niue -11 GMT163
Norfolk Island +11.5 GMT164
North Korea +9 GMT119
Norway +1 GMT167
Oman +4 GMT168
Pakistan +5 GMT169
Palau +9 GMT170
Panama -5 GMT171
Papua New Guinea +10 GMT172
Paraguay -4 GMT173
Peru -5 GMT174
Philippines +8 GMT175
Poland +1 GMT176
Portugal +1 GMT177
Puerto Rico -4 GMT178
Qatar +3 GMT179
Reunion +4 GMT181
Romania +2 GMT182
Russia – zone eight +9 GMT183
Russia – zone eleven +12 GMT184
Russia – zone five +6 GMT185
Russia – zone four +5 GMT186
Russia – zone nine +10 GMT187
Russia – zone one +2 GMT188
Russia – zone seven +8 GMT189
Russia – zone six +7 GMT190
Russia – zone ten +11 GMT191
Russia – zone three +4 GMT192
Russia – zone two +4 GMT193
Rwanda +2 GMT194
Saint Helena0 GMT212
Saint Kitts and Nevis -4 GMT213
Saint Lucia -4 GMT214
Saint Vincent Grenadines -4 GMT216
San Marino +1 GMT197
Saudi Arabia +3 GMT199
Senegal0 GMT200
Seychelles +4 GMT203
Sierra Leone0 GMT204
Singapore +8 GMT205
Slovenia +1 GMT206
Solomon Islands +11 GMT207
Somalia +3 GMT208
South Africa +2 GMT209
South Korea +9 GMT120
Spain +1 GMT210
Sri Lanka +5.5 GMT211
Sudan +2 GMT217
Swaziland +2 GMT218
Sweden +1 GMT219
Switzerland +1 GMT220
Syria +2 GMT221
Taiwan +8 GMT222
Tanzania +3 GMT224
Thailand +7 GMT225
Togo0 GMT226
Tonga +13 GMT227
Trinidad and Tobago -4 GMT228
Tunisia +1 GMT229
Turkey +2 GMT230
Turkmenistan +5 GMT231
Tuvalu +12 GMT233
Uganda +3 GMT234
United Arab Emirates +4 GMT235
United Kingdom0 GMT236
United Kingdom – Channel Islands0 GMT54
United Kingdom – New Hebrides +11 GMT237
United Kingdom – Northern Ireland0 GMT238
Uruguay -3 GMT239
USA – Alaska -9 GMT240
USA – Aleutian -10 GMT241
USA – Arizona -7 GMT242
USA – Central -6 GMT243
USA – Eastern -5 GMT244
USA – Hawaii -10 GMT245
USA – Indiana East -5 GMT246
USA – Mountain -7 GMT247
USA – Pacific -8 GMT248
Uzbekistan +5 GMT249
Vanuatu +11 GMT250
Venezuela -4 GMT252
Vietnam +7 GMT253
Wallis And Futuna Islands +12 GMT256
Yemen +3 GMT257
Zambia +2 GMT261
Zimbabwe +2 GMT262

Wel Callback System

Version 1.1

Introduction

The Wel callback system returns a simple Post request to a user’s chosen URL containing details about the success or failure of a chosen FAX, TTS or Voice message. For SMS, it will send a callback containing the reply details for a given 2 Way SMS reply, and optionally it can also do a callback when the SMS delivery/failure is confirmed. (See notes below)

There is one call back for each broadcast recipient, so a broadcast to 10 people should generate 10 status callback messages.

Configuration

The activation and setting of the callback URL is defined in two ways.

  1. On a per user basis, and is set either via the user administration page by a Wel admin (field: “callbackURL”), or via the AddUser or ModifyUser method in the API (field “callbackURL”).
  2. Via the API, the callback can be set on a per broadcast basis using the “CallbackURL” parameter

If the callbackURL parameter is blank, no callback is attempted for that user/broadcast, otherwise a callback is sent to the given URL.
The Callback URL should be of the standard format. Eg: http://testdomain.com/testscript.php

For SMS, if a callback parameter is defined, then by default callbacks are only done for 2 way SMS replies. If you need callback on SMS status updates as well, then the additional Boolean parameter: “CallbackOnSMSStatusUpdate” can be set to true, either in the API SMSJob request, or in the user administration page.

Technical details

On receipt of a final message status report from the internal Telephony systems, an asynchronous Callback request is sent to the specified URL containing the following POST fields:

Fax/Voice:
        BroadcastID: 1234567
        BroadcastName: Test Broadcast
        Timestamp: 2010-09-20T23:04:56 10:00
        Cost: 10
        Reference: TestCompany
        Recipient: TestUser
        Destination: 001133123456789
        Status: SENT
        Duration: 8
        Keypress: 2

SMS Status Update:
        BroadcastID: 1234567
        BroadcastName: Test Broadcast
        Timestamp: 2010-09-20T23:04:56 10:00
        Reference: TestCompany
        Recipient: TestUser
        Destination: 001133123456789
        Status: SENT
        HandsetDeliveryTimestamp: 2012-03-09 13:48:46

SMS Reply Details:
        BroadcastID: 1234567
        BroadcastName: Test Broadcast
        Timestamp: 2010-09-20T23:04:56 10:00
        Reference: TestCompany
        Recipient: TestUser
        Destination: 001133123456789
        Response: The msg returned by the recipient

Callback Retry:

If the reply message fails to get a valid HTML response, or the words “error” or “fail” (case insensitive) are found in the response, then the callback is queued for retry.

The message is retried with intervals between retries of: 1, 5, 15 and 45 minutes.
If no valid response after this time, then the callback is dropped.

Link In SMS

Overview

Link In SMS is a feature where custom, user specific pages of html or text data can be presented through a simple SMS message. How it works is that for each SMS recipient a custom web page will be created and linked to in their SMS, allowing viewing of the page of html with a simple click. This allows a single SMS to communicate arbitrary large amounts of data. For example, a SMS broadcast could send out employee’s individual upcoming monthly timetables, or their invested stock prices, or lists of overdue library books, etc. each accessed by a simple click in their SMS.

Implementation

There are two methods to use the Link In SMS System:

  1. The Page data can be passed in full for each user.
  2. A Link In SMS page template can be passed once for the job, and the pages generated by merging with the recipient fields.

Option 1:

With the first method of using Link In SMS through the API, the desired page data is added to the API request by adding the page data in a mergefield called “linkinsms” for each SMS recipient, and including the phrase %%linkinsms%% in your SMS message.

An example Link in SMS request would have recipient fields like:

				
					Destination = '+098765432', 
Reference = 'mytest',
FirstNane = 'John'
MergeField= [
	LinkInSMS = '<pageof html data for John’s schedule…>'
]

Destination = '+098765431', 
Reference = 'myothertest',
FirstNane = 'Jane'
MergeField= [
	LinkInSMS = '<pageof html data for Jane’s schedule…>'
]
				
			

And the SMS message could be:

“Hi %%firstname%%. Please click on %%linkinsms%% to view your schedule for next week.”

 

The resulting SMS received by the employee would look like:

“Hi Jane. Please click on http://lis.ms/3jKu738aU to view your schedule for next week.”

And clicking this would take them to their schedule in the provided page data.

 

Option 2:

The second method of including a Link In SMS page is to populate the SMSJob field “LinkInSMSPage” with a template containing merge fields. This is appropriate for simple pages where there are minor differences between the recipients’ pages.

For example:

SMSJob.LinkInSMSPage = “<p>Welcome %%firstname%%.</p><p>Please read the below Terms and Conditions</p>
<p>… Long terms and conditions …</p>”


Other details:

In both cases, if the “page content” is a just a URL, then when the recipient clicks on the link, they are redirected to the URL supplied
For example:
        Page content = “http://HealthNews.com/latest_flu_info.html
Or the link could let them access custom pages just for them:
        Page content = “http://myschedule.com/schedule.php?userid=123&auth=h6Fh89Uz


To reduce the amount of page data needed for each recipient, you can set Link In SMS header and footer values in your user profile. So you can have a Logo and other links automatically wrapped around any uploaded html content. This way you can just send the core content and all header, logo and styling are already done.

Still Not Sure How We Can Help? Call Us And Let Us Work With You To Make Your Business Easier & More Profitable.

Client Login