call-em-all web service / api

Call-Em-All Web Service / API

Version 3.2.13 (6.8.2012) Revised and Updated

1 | P a g e

Sample code is provided by Call-Em-All LLC (“CEA”) for use with CEA applications only. Sample code provided by CEA in text, images, video, and any

other media contained on this site is for learning purposes only. Sample code is provided “as is” with no warranties of any kind, express or implied.

Below you will find all of the information needed to allow you to Integrate

your application with the Call-Em-All Voice and Text delivery platform.

If you have questions or issues regarding the API or testing please use the

email address [email protected] to communicate with us.

Table of Contents

ChangeLog .................................................................................................................................... 11

How to get started ........................................................................................................................ 16

Important Notes ........................................................................................................................... 17

End Points .................................................................................................................................... 19

Conventions Used in the Document .............................................................................................. 20

REQUIRED vs OPTIONAL vs RECCOMENDED ................................................................................... 22

Function: AddNumbersToBroadcast (multiple) .............................................................................. 23

AddNumberToBroadcastRequestType .............................................................................................................. 23

AddNumberToBroadcastResponseType ........................................................................................................... 23

Function: AddNumbersToList ........................................................................................................ 25

AddNumbersToListRequestType ....................................................................................................................... 25

AddNumbersToListResponseType .................................................................................................................... 25

Function: AddNumberToBroadcast ............................................................................................... 27

AddNumberToBroadcastRequestType .............................................................................................................. 27

AddNumberToBroadcastResponseType ........................................................................................................... 27

Function: AddPersonsToList .......................................................................................................... 28

AddPersonsToListRequestType ......................................................................................................................... 28

AddPersonsToListResponseType....................................................................................................................... 28

Function: ArchiveBroadcast........................................................................................................... 29

ArchiveBroadcastRequestType ......................................................................................................................... 29

mailto:[email protected]



2 | P a g e



ArchiveBroadcastResponseType ....................................................................................................................... 29

Function: CancelBroadcast ............................................................................................................ 30

CancelBroadcastRequestType ........................................................................................................................... 30

CancelBroadcastResponseType ........................................................................................................................ 30

Function: CheckAccount ................................................................................................................ 31

CheckAccountRequestType ............................................................................................................................... 31

CheckAccountResponseType ............................................................................................................................ 31

Function: CheckKeywordAvailable ................................................................................................ 32

CheckKeywordAvailableRequestType ............................................................................................................... 32

CheckKeywordAvailableResponseType ............................................................................................................. 32

Function: CheckPhoneNumber ...................................................................................................... 33

CheckPhoneNumberRequestType .................................................................................................................... 33

CheckPhoneNumberResponseType .................................................................................................................. 33

Function: CreateBroadcast DEPRECATED (see ExtCreateBroadcast) ............................................... 34

CreateBroadcastRequestType ........................................................................................................................... 34

CreateBroadcastResponseType ........................................................................................................................ 34

Function: CreateDetailedBroadcast ............................................................................................... 36

CreateDetailedBroadcastRequestType ............................................................................................................. 36

CreateDetailedBroadcastResponseType ........................................................................................................... 37

Function: CreateNewList ............................................................................................................... 38

CreateNewListRequestType .............................................................................................................................. 38

CreateNewListResponseType ............................................................................................................................ 38

Function: CreatePersonID ............................................................................................................. 40

CreatePersonIDRequestType ............................................................................................................................ 40

CreatePersonIDResponseType .......................................................................................................................... 40

Function: CreateRecordingID ......................................................................................................... 42

CreateRecordingIDRequestType ....................................................................................................................... 42

CreateRecordingIDResponseType ..................................................................................................................... 42

Function: CreateTTS ...................................................................................................................... 43



3 | P a g e



CreateTTSRequestType ..................................................................................................................................... 43

CreateTTSResponseType ................................................................................................................................... 43

Function: DeleteAudioLib .............................................................................................................. 44

DeleteAudioLibRequestType ............................................................................................................................. 44

DeleteAudioLibResponseType .......................................................................................................................... 44

Function: DeleteList ...................................................................................................................... 45

DeleteListRequestType ..................................................................................................................................... 45

DeleteListResponseType ................................................................................................................................... 45

Function: DeleteNumberFromBroadcast ....................................................................................... 46

DeleteNumberFromBroadcastRequestType ..................................................................................................... 46

DeleteNumberFromBroadcastResponseType ................................................................................................... 46

Function: DeleteNumbersFromBroadcast (multiple) ..................................................................... 47

DeleteNumbersFromBroadcastRequestType ................................................................................................... 47

DeleteNumbersFromBroadcastResponseType ................................................................................................. 47

Function: DeletePerson ................................................................................................................. 48

DeletePersonRequestType ................................................................................................................................ 48

DeletePersonResponseType ............................................................................................................................. 48

Function: DeletePersonFromList ................................................................................................... 49

DeletePersonFromListRequestType .................................................................................................................. 49

DeletePersonFromListResponseType ............................................................................................................... 49

Function: DeleteSchedule ............................................................................................................. 50

DeleteScheduleRequestType ............................................................................................................................ 50

DeletePersonFromListResponseType ............................................................................................................... 50

Function: ExtCreateBroadcast ....................................................................................................... 51

ExtCreateBroadcastRequestType ...................................................................................................................... 51

ExtCreateBroadcastResponseType ................................................................................................................... 52

How to Customize a Survey or provide information in response to Keypresses ........................................... 54

Function: GetAccountkeywords .................................................................................................... 56

GetAccountkeywordsRequestType ................................................................................................................... 56



4 | P a g e



GetAccountKeywordsResponseType ................................................................................................................ 56

Function: GetAccountOptOuts ...................................................................................................... 57

GetAccountOptOutsRequestType ..................................................................................................................... 57

GetAccountOptOutsResponseType .................................................................................................................. 57

Function: GetAccountStatusValues ............................................................................................... 58

GetAccountStatusRequestType ........................................................................................................................ 58

GetAccountStatusResponseType ...................................................................................................................... 58

Function: GetAllBroadcastStatus ................................................................................................... 59

GetAllBroadcastStatusRequestType ................................................................................................................. 59

GetAllBroadcastStatusResponseType ............................................................................................................... 59

Function: GetAudioLib .................................................................................................................. 61

GetAudioLibRequestType .................................................................................................................................. 61

GetAudioLibResponseType ............................................................................................................................... 61

Function: GetAudioLink DEPRECATED (Broadcast ID) ..................................................................... 63

GetAudioLinkRequestType ................................................................................................................................ 63

GetAudioLinkResponseType ............................................................................................................................. 63

Function: GetAudioLinkMP3 DEPRECATED (Broadcast ID) .............................................................. 64

GetAudioLinkMP3RequestType ........................................................................................................................ 64

GetAudioLinkMP3ResponseType ...................................................................................................................... 64

Function: GetAudioLinkWAV DEPRECATED (Broadcast ID) ............................................................. 65

GetAudioLinkWAVRequestType ........................................................................................................................ 65

GetAudioLinkWAVResponseType ..................................................................................................................... 65

Function: GetAvailableCreditCardTypes ........................................................................................ 66

GetAvailableCreditCardTypesRequestType ...................................................................................................... 66

GetAvailableCreditCardTypesResponseType .................................................................................................... 66

Function: GetAvailableGroupCodes ............................................................................................... 67

GetAvailableGroupCodesRequestType ............................................................................................................. 67

GetAvailabeGroupCodesResponseType ............................................................................................................ 67

Function: GetAvailableLists ........................................................................................................... 68



5 | P a g e



GetAvailableListsRequestType .......................................................................................................................... 68

GetAvailableListsResponseType ........................................................................................................................ 68

Function: GetBroadcastResult ....................................................................................................... 69

GetBroadcastResultRequestType ...................................................................................................................... 69

GetBroadcastResultResponseType ................................................................................................................... 70

Function: GetBroadcastStatusValues ............................................................................................. 72

GetBroadcastStatusValuesRequestType ........................................................................................................... 72

GetBroadcastStatusValuesResponseType......................................................................................................... 72

Function: GetCallBalance .............................................................................................................. 73

GetCallBalanceRequestType ............................................................................................................................. 73

GetCallBalanceResponseType ........................................................................................................................... 73

Function: GetCallResultValues ...................................................................................................... 74

GetCallResultValuesRequestType ..................................................................................................................... 74

GetCallResultValuesResponseType ................................................................................................................... 74

Function: GetChargeHistory .......................................................................................................... 75

GetChargeHistoryRequestType ......................................................................................................................... 75

GetChargeHistoryResponseType ...................................................................................................................... 75

Function: GetListContents ............................................................................................................. 76

GetListContentsRequestType ............................................................................................................................ 76

GetListContentsResponseType ......................................................................................................................... 76

Function: GetListIDByName .......................................................................................................... 77

GetListIDByNameRequestType ......................................................................................................................... 77

GetListIDByNameResponseType ....................................................................................................................... 77

Function: GetListsByPersonID ....................................................................................................... 78

GetListsByPersonIDRequestType ...................................................................................................................... 78

GetListsByPersonIDResponseType .................................................................................................................... 78

Function: GetOptOutList ............................................................................................................... 79

GetOptOutListRequestType .............................................................................................................................. 79

GetOptOutListResponseType ............................................................................................................................ 79



6 | P a g e



Function: GetPersonIDDetails ....................................................................................................... 80

GetPersonIDDetailsRequestType ...................................................................................................................... 80

GetPersonIDDetailsResponseType .................................................................................................................... 80

Function: GetPersonIDsByPhone ................................................................................................... 81

GetPersonIDsByPhoneRequestType ................................................................................................................. 81

GetPersonIDsByPhoneResponseType ............................................................................................................... 81

Function: GetPhoneNumberHistory .............................................................................................. 82

GetPhoneNumberHistoryRequestType ............................................................................................................. 82

GetPhoneNumberHistoryResponseType .......................................................................................................... 82

Function: GetSchedules ................................................................................................................. 83

GetSchedulesRequestType ................................................................................................................................ 83

GetSchedulesResponseType ............................................................................................................................. 83

Function: GetSMSInbox ................................................................................................................. 85

GetSMSInboxRequestType ................................................................................................................................ 85

GetSMSInboxResponseType ............................................................................................................................. 85

Function: GetSMSOptIns ............................................................................................................... 87

GetSMSOptInsRequestType .............................................................................................................................. 87

GetSMSOptInsResponseType ............................................................................................................................ 87

Function: GetSMSResultValues ..................................................................................................... 88

GetSMSResultValuesRequestType .................................................................................................................... 88

GetSMSResultValuesResponseType .................................................................................................................. 88

Function: InsertCustomCall ........................................................................................................... 89

InsertCustomCallRequestType .......................................................................................................................... 89

InsertCustomCallResponseType ........................................................................................................................ 89

Function: InsertOptOut ................................................................................................................. 91

InsertOptOutRequestType ................................................................................................................................ 91

InsertOptOutResponseType .............................................................................................................................. 91

Function: LinkKeywordToList ........................................................................................................ 92

LinkKeywordToListRequestType ....................................................................................................................... 92



7 | P a g e



LinkKeywordToListResponseType ..................................................................................................................... 92

Function: ProvideAudio ................................................................................................................. 93

ProvideAudioRequestType ................................................................................................................................ 93

ProvideAudioResponseType ............................................................................................................................. 93

Function: RenameList .................................................................................................................... 94

RenameListRequestType ................................................................................................................................... 94

RenameListResponseType ................................................................................................................................ 94

Function: RetrieveAudio ............................................................................................................... 95

RetrieveAudioRequestType ............................................................................................................................... 95

RetrieveAudioResponseType ............................................................................................................................ 95

Function: RetrieveRecordingIDs .................................................................................................... 96

RetrieveRecordingIDsRequestType ................................................................................................................... 96

RetrieveRecordingIDsResponseType ................................................................................................................ 96

Function: ScheduleDaily ................................................................................................................ 98

ScheduleDailyRequestType ............................................................................................................................... 98

ScheduledailyResponseType ............................................................................................................................. 99

Function: ScheduleWeekly .......................................................................................................... 100

ScheduleWeeklyRequestType ......................................................................................................................... 100

ScheduledailyResponseType ........................................................................................................................... 101

Function: SendOptInvitation ....................................................................................................... 102

SendOptInvitationRequestType ...................................................................................................................... 102

SendOptInvitationResponseType .................................................................................................................... 102

Function: UpdateAccountInfo ..................................................................................................... 103

UpdateAccountInfoRequestType .................................................................................................................... 103

UpdateAccountInfoResponseType .................................................................................................................. 103

Function: UpdateCreditCard ........................................................................................................ 104

UpdateCreditCardRequestType ...................................................................................................................... 104

UpdateCreditCardResponseType .................................................................................................................... 104

Function: UpdatePersonID .......................................................................................................... 106



8 | P a g e



UpdatePersonIDRequestType ......................................................................................................................... 106

UpdatePersonIDResponseType ....................................................................................................................... 106

Function: UpdateSMSInboxStatus ............................................................................................... 107

UpdateSMSInboxStatusRequestType.............................................................................................................. 107

UpdateSMSInboxStatusResponseType ........................................................................................................... 107

Function: WB_CreateAccount RESTRICTED USE........................................................................... 108

WB_CreateAccountRequestType .................................................................................................................... 108

WB_CreateAccountResponseType .................................................................................................................. 108

Function: WB_FundAccount RESTRICTED USE ............................................................................ 110

WB_FundAccountRequestType....................................................................................................................... 110

WB_FundAccountResponseType .................................................................................................................... 110

Function: WBCreateAccount RESTRICTED USE / DEPRECATED ..................................................... 111

WBCreateAccountRequestType ...................................................................................................................... 111

WBCreateAccountResponseType.................................................................................................................... 111

Function: WBFundAccount RESTRICTED USE / DEPRECATED ....................................................... 113

WBFundAccountRequestType ........................................................................................................................ 113

WBFundAccountResponseType ...................................................................................................................... 113

Function: WBPreVerifyAccount RESTRICTED USE / DEPRECATED ................................................. 114

WBPreVerifyAccountRequestType .................................................................................................................. 114

WBPreVerifyAccountResponseType ............................................................................................................... 114

Function: WBUDIDLookup RESTRICTED USE / DEPRECATED ......................................................... 115

WBUDIDLookupRequestType .......................................................................................................................... 115

WBUDIDLookupResponseType ....................................................................................................................... 115

Perl Example ............................................................................................................................... 116

ExtCreateBroadcast.pl ..................................................................................................................................... 116

PHP Example............................................................................................................................... 118

ExtCreateBroadcast.php ................................................................................................................................. 118

CheckAccount.php .......................................................................................................................................... 120

Python Examples ........................................................................................................................ 120



9 | P a g e



CheckAccount.py ............................................................................................................................................. 120

ExtCreateBroadcast.py (with Proxy) ............................................................................................................... 122

.................................................................................................................. 122

CheckAccount.py ............................................................................................................................................. 123

.................................................................................................................. 123

GetbroadcastResult.py .................................................................................................................................... 124

.................................................................................................................. 124

Bash + cURL Example .................................................................................................................. 125

GetListContents.sh .......................................................................................................................................... 125

VBA Example .............................................................................................................................. 126

C++ Example ............................................................................................................................... 129

Visual Studio VB.net & C# Example ............................................................................................. 132

Step 1 Creating the Project ............................................................................................................................. 133

Step 2 Build the Form ...................................................................................................................................... 134

Step 3 Add the Web Reference ....................................................................................................................... 135

C#..................................................................................................................................................................... 140

......................................................................................................................................................................... 140

VB.Net ............................................................................................................................................................. 141

ErrorCodes and ErrorMessages ................................................................................................... 143

Extended Descriptions ................................................................................................................ 144

audioID ............................................................................................................................................................ 144

broadcastID ..................................................................................................................................................... 144

broadcastType ................................................................................................................................................. 144



10 | P a g e



callerID ............................................................................................................................................................ 145

commaDelimitedPhoneNumbers .................................................................................................................... 145

listID ................................................................................................................................................................ 146

launchDateTime .............................................................................................................................................. 146

messageID ....................................................................................................................................................... 146

messageIDVM ................................................................................................................................................. 146

personID .......................................................................................................................................................... 146

phoneNumberCSV ........................................................................................................................................... 147

phoneNumberSource ...................................................................................................................................... 147

pin .................................................................................................................................................................... 147

smsMsg............................................................................................................................................................ 148

TTSText ............................................................................................................................................................ 148

username ........................................................................................................................................................ 148

Text to Speech ............................................................................................................................ 149

Available Voices .............................................................................................................................................. 149

Examples of speaking specific data-types ....................................................................................................... 149

Special Pronunciations (Phonetic Spelling) ..................................................................................................... 150

Inserting Pauses .............................................................................................................................................. 153

Prosody - Changing the pitch, range, rate and volume ................................................................................... 153

Staging Considerations ................................................................................................................ 155

SMS .................................................................................................................................................................. 155

Voice ................................................................................................................................................................ 155

How Does SMS work at Call-Em-All ............................................................................................. 156

HOWTO-SMS .............................................................................................................................. 158

Enabling Text on an Account ........................................................................................................................... 158

How to Opt People in ...................................................................................................................................... 160

The 10,000 foot view .................................................................................................................. 162



11 | P a g e



ChangeLog

3.2.13 – 5/2/2012

New function GetPhoneNumberHistory retrieve all past calls for a number

Added startDate/stopDate search filters to GetAccountOptOuts, GetOptOutList, GetSMSInbox, GetSMSOptIns

Added startDate/stopDate search filters to GetAllBroadcastStatus, GetCallBalance, GetChargeHistory

Display "Orphaned" opt-ins that no longer belong to a group in GetSMSOptIns

Added new Restricted function WB_CreateAccount and WB_FundAccount

New function GetListsByPhone to show all lists that a phone number belongs to

Added ListID to results of GetListContents

Added new Return Detail array to AddNumbersToList, also return the ListID for asynch calls

Now return broadcastID in results of AddNumberToBroadcast, AddNumbersToBroadcast

Now return listID in results of AddPersonsToList

Now return broadcastID in results of AudioSalesCheck

Now return broadcastID in results of ArchiveBroadcast

Now return broadcastID in results of CancelBroadcast

Now return username in results of CheckAccount

Now return keyword in results of CheckKeywordAvailable

Now return phonenumber in results of CheckPhonenumber

Now return listID in results of DeleteList

Now return broadcastID, phoneNumber in results of DeleteNumberFromBroadcast

Now return personID in results of DeletePerson

Now return personID, listID in results of DeletePersonFromList

Now return jobName in results of DeleteSchedule

Now return listID in results of GetListContents

Now return listname in results of GetListIDByName

Now return personID in results of GetListsByPersonID

Now return personID in results of GetPersonIDDetails

Now return phonenumber in results of GetPersonIDsByPhone

Now return phonenumber in results of InsertOptOut

Now return listID, Keyword in results of LinkKeywordToList

Now return audioID in results of RetrieveAudio

Now return BroadcastName in results of ScheduleDaily

Now return BroadcastName in results of ScheduleWeekly

Now return invitePhoneNumber in results of SendOptInvitation

Now return cardNumber in results of UpdateCreditCard

Now return broadcastID in results of GetBroadcastResult

Now return AudioDescription in results of ProvideAudio

Now return AudioID in results of DeleteAudioLib

Added secure HTML access point for Audio retrieval

Added SMSname, Firstname, LastName, TimeZoneOffset, ObservesDST, Phone, Email to response data from CheckAccount

WB_CreateAccount and WB_FundAccount now suport AES encryption to verify authenticity of transactions

CreateTTS can now return WAV or MP3 results

Added support for BroadcastTimeZone in ExtCreateBroadcast

Added support for ad-hoc phone numbers via commaDelimitedPhoneNumbers in scheduleWeekly and scheduleDaily

Added Return of SMSMsg to GetBroadcastResult

GetSMSInbox can now also be filtered by phoneNumber

3.2.12 – 2/12/2012

New function GetSchedules, retrieve all schedules for an account

New Function DeleteSchedule, delete a schedule that we created with Schedule(Daily/Weekly)

New Function CreateRecordingID (can give instruction to person to record) does not need a broadcast

New Function RetrieveRecordingIDs - List recording ID's that have not had messages recorded yet

New Function GetSMSInboxStatus - Returns the different status values that an SMSInbox message can be in

New Function GetSMSMessageTypes - Enumerates the different types of messages that are in the SMSInbox

New Function UpdateSMSInboxStatus - mark messages as read, un-read, and deleted

Added startDate and stopDate filters to GetAccountOptOuts

Added startDate and stopDate filters to GetOptOutList

Added startDate and stopDate filters to GetSMSInbox

Added startDate and stopDate filters to GetSMSOptIns

Corrected issue where audio files were "locked" when broadcasts were going out

Added startDate and stopDate filters to GetChargeHistory

Added startDate and stopDate filters to GetCallBalance



12 | P a g e



Added startDate and stopDate filters to GetAllBroadcastStatus

3.2.11 – 11/13/2011

New function to be used on integrations to allow support of Sales Introductions.. AudioSalesCheck

New function ScheduleDaily to set calls to occur every X days with options for repeating (reminders)

New function ScheduleWeekly to set calls to occur every X weeks on specific days (ie Tuesday and Friday) at 4:00pm

New function SendOptInvitation to send an invite to an SMS User to join a group

ExtCreateBroadcast can now set a throttle value for a broadcast

ExtCreateBroadcast can specify answerhandling. Force Ans machine behavior or live answer reguardless

New function ArchiveBroadcast moves BC out of results (space and size management of result sets)

Added more backend logging of HTTP Context and Environment, for Proxies handle the x-forwarded-for

Support for widget joining list “0” or everyone via top level keyword

Standardized all dates returned so that they can be parsed by SQL etc..

Code Cleanup and Refactoring with ReSharper R#

Fixed issues with Large high bitrate MP3 files consuming too much memory and failing

Corrected issue in CreatePersonID to handle null secondary and tertiary numbers

New function LinkKeyWordToList to manage opt-ins for SMS 3.2.10 – 8/04/2011

ExtCreateBroadcast now supports broadcast Types 4 and 5 for combination broadcasts

Added “actualCallUnitsUsed” to GetAllBroadcastStatus

Added MaxCallUnitsUsed and ActualCallUnitsUsed to GetBroadcastResult

Added Function GetSMSInbox to pull responses, join requests etc from SMS broadcasts

Added function CheckPhoneNumber

Added “SMSJoinKey” to results of WBCreateAccount

Provide more detail on a callUnitsException (was returning -1)

RetrieveAudio now allows message retrieval even when account is past/due or in jeopardy

Fixed issues with VBR (variable bit rate) MP3’s

Added “sortField” to GetAllBroadcastStatus (def=Broadcast Date, 1 – Broadcast creation date)

Added “CreateTimeStamp” to GetAllBroadcastStatus

Added Function ArchiveBroadcast to manage completed broadcasts

FIX: GetAllBroadcastStatus – return dates/times in Users TimeZone

FIX: What callerID to use for WhiteBox customer set during WBCreateAccount

FIX: combination of Raw AU files and SUN AU files caused issues when trying to play or concatenate

Added “userComment” to ProvideAudio for more detailed AudioLibrary data

FIX: issue where tempBroadcastID was left in broadcastID if no voice records were found on combo broadcast

FIX: RetrieveAudio performs more exhastive audio ownership checks

3.2.9 – 6/09/2011

Added function AddPersonsToList

Added function CreatePersonID

Added function GetListsByPersonID

Added function GetPersonIDDetails

Added function GetPersonIDsByPhone

Modified UpdateAccountInfo: changed multiple fields to optional, will update only if data provided now can also update the Pin (field newPin) and can update TimeZone and DST flag

Added function WBUDIDLookup to support whitebox customers 3.2.8 – 5/30/2011

Added function GetListIDByName

Added function WBCreateAccount

Added function WBFundAccount

Added function WBPreVerifyAccount

Added answerHandling to ExtCreateBroadcast 0-Automatically Determine, 1-Force Live answer, 2-Force answering machine

Added function addNumbersToBroadcast (Multiple adds at one time)

Added function deleteNumbersFromBroadcast (Multiple deletes at one time)



13 | P a g e



3.2.7 – 4/19/2011

Added function CheckKeywordAvailable Added surveyOptions array to control call more tightly in ExtCreateBroadcast

Updated UpdateCreditCard function

Fixed RetrieveAudio to properly return mp3 as well as wav and retrieve the length

Added throttle to ExtCreateBroadcast to allow user to set MAX Simultaneous calls at one time

Added first and last name to failed numbers results

Added support for new pricing of Text/SMS as ½ credit

Added back end logging of full request and response. Prepare for user queries/debugging.

Added fields to CreateTTS (IsSalesIntro, IsFavorite , AudioDescription)

CheckAccount now returns more information about account: CallerID, CallingWindowStart, CallingWindowStop, ContinueOnNextDay, TimeZone, CallRetries, MaxMessageLength, CallThrottle

Added LinkKeywordToList function for SMS Opt-Ins

CreateNewList can now specify an AutoReplyMessage if using the list for SMS Opt Ins

3.2.6 – 3/06/2001

Added C++ example to document

Added proxy examples in Python

Added function RetrieveAudio

Added field AudioLength to ProvideAudio function

3.2.5 – 2/26/2011

Added support to return MaxMessageLength, MaxCallUnitsUsed in ExtCreateBroadcast

Added message length support to CreateTTS 3.2.4 – 2/21/2011

Fixed bug in GetBroadcastResult no longer returns empty array for SMS broadcast values

FileUploadError structure now contains the offending phone number

New error type for rejected phone numbers added for SMS broadcast where the phonenumber has not Opted in to receive SMS. ErrorCode=7, "SMS Broadcast selected, but number not OPTED-IN."

3.2.3 – 2/20/2011

Added SMSBroadcastID to ExtCreateBroadcast (broadcastID was incorrect value when SMS broadcast type was specified)

GetAllBroadcastStatus now supports SMS broadcasts

Added GetCallResultValues

Added GetSMSResultValues

Added Code sample for VBA

Added Docs Staging Considerations, How Does SMS work at Call-Em-All, and HOWTO-SMS 3.2.2 – 2/17/2011

Advanced client logging by IP address etc

Implemented new exception for SMS broadcasts that have no valid opt-ins in ExtCreatBroadcast

Added Code samples Python, Bash+cURL

“How to Get Started”, “Protocols and Specifications”, “End Points”, “Conventions Used in this Document” and “Required vs Optional vs reccomended” were all added to the Documentation

3.1 – 2/11/2011

Fixed typo changed brodcastdetail -> broadcastdetail in GetBroadcastResultResponseType

Added function GetAudioLib

Implemented tbAPIErrorCodes and standardized all error codes and reporting

Added support for TTS in ExtCreateBroadcast

Added support for delimited data in commaDelimitedPhoneNumbers can supply multiple values such as first/last name, secondary/tertiary phone numbers, notes.

Added functions AddNumberToBroadcast and DeleteNumberFromBroadcast

Corrected issue where returned times were in CST instead of the users TimeZone.

Moved all application settings to Database to make releases easier and to be able to update content dynamically.

Added function ProvideAudio



14 | P a g e





15 | P a g e



3.0 – 1/1/2011

Upgrade backend audio processing to use AlvasAudio, removed dependancies on Lame, LibSampleRate, MadLib, Aumpel, etc

Implemented IsAPIAuthorized, IP Whitelisting

Extended InsertCustomCall to send TTS messages

Enhanced Error and Usage logging

Added Function AddNumberToBroadcast

Added Function CreateTTS

Added function UpdateAccountInfo

Added function UpdateCreditCard

Added Function DeleteAudioLib

Added function GetSMSOptIn (all or by listID)

Added Function DeletePerson

Added Function Get AudioLib

Added Function GetAudioLinkMP3/WAV

Added Function GetCallBalance

Added Function GetCallResultValues

Added Function GetChargeHistory

Added Function GetOptOutList

Added Function GetSMSOptIns 2.0 Considered Intial Release

CancelBroadcast

CreateBroadcast

GetBroadcastResult

InsertCustomCall



16 | P a g e



How to get started

You need to have an existing account, If you do not have an account then please visit our site at

http://www.call-em-all.com and create a new free trial account. Look in the bottom left corner of the

screen for :

Then when you are logged in, browse to http://www.call-em-all.com/dev or look for the Developer

portal link at the bottom of the screen:

From this point select “Get API Authorization” and fill out the contact form where you will tell a little

about yourself and what your application is. We will use the data on the form to create you a staging

account to Develop and Test your application.

Once you have your application working, you can email us at [email protected] and request to have

your account “certified” or authorized to use the production system.

The application that you have developed can be immediately used to access our production system

with the same credentials as you created above, the only change will be that the EndPoint will

change from Staging to production (see End Points below) so it is reccomended that you use a variable

in your code to represent the EndPoint so only one change is needed to move from Staging to

Production.

http://www.call-em-all.com/

http://www.call-em-all.com/dev




17 | P a g e



Important Notes

If you plan to be working with TEXT or SMS Messaging…

Please see the section of our Documentation called

STAGING CONSIDERATIONS

There are a few differences that are outlined on how the system behaves In staging vs production, and a few minutes of reading could save

you several hours of frustration and confusion



18 | P a g e



Protocols and specifications We support both SOAP 1.1 and SOAP 1.2 requests.

For implementation help please see our code examples in this document or visit:

http://www.call-em-all.com/dev/code-samples.aspx

http://www.call-em-all.com/dev/code-samples.aspx



19 | P a g e



End Points

Staging Environment:

HTTP: http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx

Secure/SSL (Recommended): https://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx

Production Environment:

HTTP: http://api.call-em-all.com/webservices/ceaapi_v2.asmx

Secure/SSL (Recommended): https://api.call-em-all.com/webservices/ceaapi_v2.asmx

http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx


http://api.call-em-all.com/webservices/ceaapi_v2.asmx




20 | P a g e



Conventions Used in the Document

All functions are accessed by passing in a Request Structure and the output or result is returned in a Reponse

Structure.

The naming conventions are pretty straight forward. A function named CreateTTS would be passed data by

filling out the structure CreateTTSRequestType and when consumed, would return its results in

CreateTTSResponseType.

For example in C# the RequestType for CreateTTS would be:

public struct CreateTTSRequestType

{

public string username; //Required - The CEA Username of the account

public string pin; //Required - The CEA Pin of the account

public string TTSText; //Required - The Text to Speech to say

public string RequestedAudioFormat; //Optional - Default=0 [0-Wav,1-MP3] (currently only supports Wav)

public string SaveInLibrary; //Optional - Default=0 [0=Do Not Save, 1=Save and return AudioID]

}

In our documentation, this would be shown as:

The Request Object to be passed in: CreateTTSRequestType

Parameter Data Type Description / Values Required?

username Numeric String The CEA Username of the account Required

Pin Numeric String The CEA Pin of the account Required

TTSText String The text you wish to have converted to speech Required

RequestedAudioFormat Numeric String Def=0; 0-WAV, 1-MP3 Optional

SaveInLibrary Numeric String Save in the audioLibrary Def=0; 0-No, 1-Save Optional

Our API uses Strings for a majority of its parameters, so we will try to describe the expected data in the Data

Type. For example, our usernames are numeric sequences, and in most cases we ask the user to use a

phonenumber as their username (something they can easily remember). We use numeric because if the user

wants to log in and create a broadcast over the phone, it is much easier to key in a number than work out

number to character conversions. So while our system “can” use alphanumeric and special characters, we use

business logic to restrict it to numeric only.

For other fields, String is just what you would expect. In fact, for the CreateTTS function special markup can be

used in the TTSText parameter to make sure that the voice speaking your text is saying what you want (Dates,

Times, Dollars, Ordinals and of course Phonenumbers) see the addendum on Text to Speech for more information.



21 | P a g e



Once you have populated your Request and submitted it to our API, we will process it and send you back a

Response. The example response in C# looks like this:

public struct CreateTTSResponseType

{

public int errorCode; // Returns 0 if the function was successful,

// otherwise it will return an error code

public string errorMessage; // The error message cooresponding with the error code

public byte[] TTSAudio; // Formatted audio stream.

public string AudioID; // Returned when SaveInLibrary = 1

}

We would describe this in our documentation as:

The Response Object returned by our web service: CreateTTSResponseType

Parameter Data Type Description / Values

errorCode Integer Returns 0 if the function was successful, otherwise it will

return an error code

errorMessage String The error message corresponding with the error code

byte[] TTSAudio Binary The audio stream, save to file or pass to browser to play

AudioID String Returns the audioID for reference when saved in library

In this case, we are returning several types of data. The errorcode (an integer), the human readable

errorMessage, a binary message and an audioID.

Currently we only return binary messages that contain Audio Data. Depending on the format you have

selected, you would be able to save this binary message directly to disk and name it accordingly and play the

audio, or in a web environment, send out a content header (ie audio/wav) and dump out the binary to allow a

user to listen to the audio.

For reference, we have included sample code to get your started in PERL, PHP, and .NET C#. We plan to add

Python soon and .NET VB if we get any requests.



22 | P a g e



REQUIRED vs OPTIONAL vs RECCOMENDED

Required Parameters (such as Username or Pin) are neccesary for the method to complete, if a required

parameter is left empty/blank/null then the API will return an errorcode and errormessage describing the

parameter that is missing. For a full listing see errorcodes and errormessages

Examples:

errorCode errorMessage 160 Required parameter 'username' is missing

161 Required parameter 'pin' is missing

162 Required parameter 'broadcastID' is missing

Optional Parameters These parameters will have default values specified in the documentation, if you want to

take the default, you can either send a null string or not pass the parameter at all. If the optional parameter is

specified and it does not match the requested input type or contents, an errorcode and errormessage

describing the expected input will be returned.

Examples:

errorCode errorMessage 126 Unexpected value for surveyResultFilter; Expecting *,0,1,2,3,4,5,6,7,8, or 9

112 Unexpected value for checkMaxPhoneCount; Expecting 0 or 1

119 launchDateTime must be in MM/DD/YYYY HH:MM AM/PM format

Recommended Parameters These parameters are usually for describing data that you are sending via the API,

the best example would be when you are using ProvideAudio to upload audio files to be used on upcoming

broadcasts. These files are stored in your audio library and we assign them an audioID, without your

description it will be difficult to manage which file is which.



23 | P a g e



Function: AddNumbersToBroadcast (multiple)

Add MULTIPLE new phonenumbers to an existing Broadcast

This function accepts 1 parameter, the request, and returns a response. Function Call: AddNumbersToBroadcastResponseType AddNumbersToBroadcast(AddNumbersToBroadcastRequestType myRequest)

The Request Object to be passed in:

AddNumberToBroadcastRequestType

Parameter Data Type Description / Values Required? username Numeric String The CEA Username of the account Required

pin Numeric String The CEA Pin of the account Required

broadcastID Numeric String The BroadcastID to add the numbers to Required

NumbersArray[] numbersToAdd Array Array of phoneNumbers to add Required

NumbersArray Type:

Parameter Data Type Required?

phoneNumber Numeric String Required

firstName String Optional

lastName String Optional

The Response Object returned by our web service:

AddNumberToBroadcastResponseType


errorCode Integer Returns 0 if the function was successful, otherwise it

will return an error code


ResultsArray[] addResults Array Results of each addition request

ResultsArray Type:


phoneNumber Numeric String The phoneNumber

errorCode Integer Result of attempted add

errorMessage String Error message

Return/Error Codes:

Code Description 0 Function executed successfully

-1 Unexpected Error

101 PhoneNumber does not contain 10 digits

102 PhoneNumber is not in the continental US, Puerto Rico, Hawaii, or Canada

103 PhoneNumber is on the Call-em-all Opt Out list

104 Authentication failed - username or pin is invalid

105 Account is inactive. Please contact customer support.

106 Account does not have enough credits

107 Account is not authorized to use the CEAAPI

132 Access denied - broadcastID does not belong to this account

135 BroadcastID is not numeric

136 Broadcast is not active



24 | P a g e





25 | P a g e



Function: AddNumbersToList

Return status of addition of numbers to an existing list

This function accepts 1 parameter, the request, and returns a response. Function Call: AddNumbersToListResponseType AddNumbersToList(AddNumbersToListRequestType myRequest)


AddNumbersToListRequestType



listID Numeric String 0 – Everyone, N – Specific list to add to

Blank/Null defaults to Everyone Required

NumbersToAdd array of

ListAddDetailData[] Array Persons to add Required

ListAddDetailData Type:


PrimaryPhone String (phonenumber) Required

FirstName String Optional

LastName String Optional

Notes string Optional

SecondaryPhone String (phonenumber) Optional

TertiaryPhone String (phonenumber) Optional


AddNumbersToListResponseType


errorCode Integer

Returns 0 if the function was successful, otherwise it


NOTE: This can return 0 and still have failed inserts, you

need to check the failed Inserts array


FailedInserts array of

FailedRecordData[] Array Error results

FailedRecordData Type:


EntryNumber Integer The zero based number of the entry that failed

errorMessage String The error message



26 | P a g e



Return/Error Codes:


-1 Unexpected Error





140 ListID specified was not found

160 Required parameter 'username' is missing




27 | P a g e



Function: AddNumberToBroadcast

Return status of addition of a SINGLE phoneNumber to an existing broadcast

This function accepts 1 parameter, the request, and returns a response. Function Call: AddNumberToBroadcastResponseType AddNumberToBroadcast(AddNumberToBroadcastRequestType myRequest)


AddNumberToBroadcastRequestType



broadcastID Numeric String The broadcastID to add the number to Required

phoneNumber Numeric String The phoneNumber to add Required

firstName String Displayed on results Optional

lastName String Displayed on results Optional


AddNumberToBroadcastResponseType





broadcastID String The broadcastID submitted

phoneNumber String The phoneNumber submitted

Return/Error Codes:


-1 Unexpected Error













163 Required parameter 'phoneNumber' is missing



28 | P a g e



Function: AddPersonsToList

Return status of addition of a multiple PersonID’s to a List

This function accepts 1 parameter, the request, and returns a response. Function Call: AddpersonsToListResponseType addPersonsToList(AddPersonsToListRequestType myRequest)


AddPersonsToListRequestType



listID Numeric String The listID to add the Persons to Required

AddPersonsToListDetailData[] PersonIDsToAdd

Array Required

AddPersonsToListData Type:


personID Numeric String The personID


AddPersonsToListResponseType





PersonsFailedRecordData[] FailedInserts

Array

PersonsFailedRecordData Type:


personID Numeric String The personID


Return/Error Codes:


-1 Unexpected Error
















29 | P a g e



Function: ArchiveBroadcast

Archives a broadcast immediately instead of waiting 90 days, used to keep lists smaller

This function accepts 1 parameter, the request, and returns a response. Function Call: ArchiveBroadcastResponseType ArchiveBroadcast(ArchiveBroadcastRequestType myRequest)


ArchiveBroadcastRequestType



broadcastID Numeric String The broadcastID to archive Required


ArchiveBroadcastResponseType





broadcastID String The broadcastID that was specified

Return/Error Codes:


-1 Unexpected Error















30 | P a g e



Function: CancelBroadcast

CancelBroadcast allows the user to Cancel one of their existing active broadcast.

This function accepts 1 parameter, the request, and returns a response. Function Call: CancelBroadcastResponseType CancelBroadcast(CancelBroadcastRequestType myRequest)


CancelBroadcastRequestType



broadcastID Numeric String The CEA Broadcast ID to cancel Required


CancelBroadcastResponseType





broadcastID Numeric String The broadcastID requested to cancel

Return/Error Codes:


-1 Unexpected Error




131 broadcastID not found



136 Broadacst is not active






31 | P a g e



Function: CheckAccount

Get account status

This function accepts 1 parameter, the request, and returns a response. Function Call: CheckAccountResponseType CheckAccount(CheckAccountRequestType myRequest)


CheckAccountRequestType




CheckAccountResponseType


errorCode Integer Returns 0 if the function was successful, otherwise

it will return an error code


accountStatus Integer 0 if in good standing, 104-Bad user,105-inactive

106-credit issues,107-blocked from API

accountStatusDescription String Text of account status

CallBalance Integer Current Call Balance

PendingCallbalance Integer Total of outstanding broadcasts

AvailableCallUnits Integer Available for calls/texts

CallerID String Default CallerID

CallingWindowStart String Earliest to make calls

CallingWindowStop String When calls stop processing

ContinueOnNextDay String Do calls resume next day if did not complete

TimeZone String Accounts timezone

CallRetries String Default how many retries to attempt

MaxMessageLength String Account Max message length

CallThrottle String Max simultaneous calls

username Numeric String The requested Username

SMSName String The top-level SMS keyword for the account

FirstName String Account First name

Lastname String Account Last name

ObservesDST String 1-yes, 0-no

TimeZoneOffset String Hours offset from CST (Server time)

Phone String Users Phone number

Email String System email on file for customer

Return/Error Codes:


-1 Unexpected Error

100 Required parameter missing








32 | P a g e



Function: CheckKeywordAvailable

Checks if a keyword is available for use

This function accepts 1 parameter, the request, and returns a response. Function Call: CheckKeywordAvailableResponseType CheckKeywordAvailable(CheckKeywordAvailableRequestType myRequest)


CheckKeywordAvailableRequestType



keyword String The keyword to check Required


CheckKeywordAvailableResponseType





keyword String The keyword that was checked

Return/Error Codes:


-1 Unexpected Error






169 Requested keyword is not available

198 Cannot check the availability of another Accounts sub-keywords



33 | P a g e



Function: CheckPhoneNumber

Check if system can call a number

This function accepts 1 parameter, the request, and returns a response. Function Call: CheckPhoneNumberResponseType CheckPhoneNumber(CheckPhoneNumberRequestType myRequest)


CheckPhoneNumberRequestType



phonenumber Numeric String The phoneNumber to check Required


CheckPhoneNumberResponseType





Phonenumber Numeric String The phonenumber that was checked

Return/Error Codes:


-1 Unexpected Error








163 Required parameter phoneNumber is missing





34 | P a g e



Function: CreateBroadcast DEPRECATED (see ExtCreateBroadcast)

CreateBroadcast is the only function call required to launch a broadcast. A single call can include many phone numbers to call, the type of

call (survey or announcement), and the date/time to make the calls. The return object will include a toll free number to call and a PIN code

to record a message if a message was not provided, along with confirmation information regarding the phone numbers supplied.

This function accepts 1 parameter, the request, and returns a response. Function Call: CreateBroadcastResponseType CreateBroadcast(CreateBroadcastRequestType myRequest)


CreateBroadcastRequestType



broadcastType Numeric String 1=Announcement; 2=Survey Required

phoneNumberSource Numeric String 1=SavedList; 2=CSV; 3=Comma Delimited String of

Phone Numbers Required

broadcastName String The name of the broadcast Required

listID Numeric String The listID to send calls to Optional

phoneNumberCSV Byte[] The CSV file containing the phone numbers to

call. Required if phoneNumberSource=2 Optional

messageID

*supports audioID values Numeric String

The broadcastID corresponding to the LIVE ANSWER

message to use; Pass in a value if you would

like to use a message from a previous broadcast.

Optional

messageIDVM

*supports audioID values Numeric String

The broadcastID corresponding to the VOICE MAIL

message to use; Only applicable for survey

broadcasts. Pass in a value if you would like

to use a message from a previous broadcast.

Optional

launchDateTime Date String Default=current date/time; The date/time to

broadcast in MM/DD/YYYY HH:MM AM/PM format Optional

checkCallingWindow Numeric String Default=1; 0=Bypass calling window check;

1=Enforce calling window check; Optional

callerID Numeric String Optional - Default=account setting; The caller

ID number to display Optional

commaDelimitedPhoneNumbers String Optional - set phoneNumberSource = 3 to use this

instead of the byte array. Optional

* An audioID is generated when you upload Audio using ProvideAudio or when you specify to save the results in CreateTTS


CreateBroadcastResponseType


errorCode Integer Returns 0 if the function was successful,

otherwise it will return an error code


broadcastID String The broadcastID used to reference this broadcast

messageRecordingID String The messageRecordingID to enter when calling the 877 to record

the message for this broadcast

tollFreeNumber String The toll free number to call to record the message

goodRecordCountOnFile integer Good rec count – Default 0, populated if file used

badRecordCountOnFile integer Bad rec count – Default 0, populated if file used

duplicateRecrodCountOnFile integer Duplicate rec count – Default 0, populated if file used

totalRecordCountOnFile integer Total record count – Default 0, populated if file used

fileUploadErrors array of

FileUploadErrors[] array A list of all errors found on the file - populated if file used



35 | P a g e



FileUploadErrors Type:

Parameter Data Type Comments

LineNumber Integer The line number of the error on the file

errorCode Integer The error code corresponding to the error

message

ErrorMessage String The error message

Return/Error Codes:


-1 Unexpected Error




106 Account does not have enough call units


108 MessageID is not valid

115 Unexpected value for broadcastType, Expecting 1 or 2

114 Unexpected value for checkCallingWindow; Expecting 0 or 1

116 Unexpected value for phoneNumberSource, Expecting 1 or 2

117 broadcastType=1, but phoneNumberCSV is not supplied

118 broadcastType=2, but listID is not supplied

119 Datetime must be in MMDDYYYY HH: MM AMPM format

120 Datetime must be in the future

121 launchDateTime is outside of your calling window

122 Not enough call units to launch this broadcast

123 No good records found in phoneNumberCSV

133 CallerID does not contain 10 digits

134 Caller ID number can not be a call-em-all number

137 phoneNumberSource=3, commaDelimitedPhoneNumbers not supplied

155 You specified an invalid listID



167 Required parameter 'broadcastType' is missing

168 Required parameter 'phoneNumberSource' is missing

169 Required parameter 'broadcastName' is missing



36 | P a g e



Function: CreateDetailedBroadcast

Features different from ExtCreateBroadcast

Can launch a broadcast with Voice/Text-to-Speech where each recipient can receive a different message.

CreateDetailedBroadcast is the function to call if not all of your numbers should receive the same message. A broadcast can include many

phone numbers to call, the type of call (survey/ announcement), and the date/time to make the calls. Unlike ExtCreateBroadcast the call has

to specify the message to be played for all recipients, either directly or by the default message. Numbers with missing audio will be omitted

from the broadcast and returned in the response’s failedTTSCallDetails field.

This function accepts 1 parameter, the request, and returns a response. Function Call: CreateDetailedBroadcastResponseType CreateDetailedBroadcast(CreateDetailedBroadcastRequestType

myRequest)


CreateDetailedBroadcastRequestType

Parameter Data Type Description /Values Required?



broadcastType Numeric String 1=Announcement;

2=Survey; Required


launchDateTime String

Default=current date+time;

The date+time to launch the broadcast

Format: MM/DD/YYYY HH:MM AM/PM

Optional

checkCallingWindow Numeric String

Default=1;

0=Bypass calling window check;

1=Enforce calling window check;

Optional

callerID Numeric String The caller ID number to display

Default=account setting; Optional

Survey[] Array of Surveyoptions Set up custom responses for *[x] keypresses Optional

Throttle Numeric String Send no more than X simultaneous calls Optional

answerHandling Numeric String

Def=0-Automatically determine

1-Assume all answers are live

2-Assume all answers are voicemail

Optional

notifyEmail String If provided send results to the email address Optional

defaultAudio DetailedBroadcastAudio default audio is used in place where audio detail

is not specified Optional

callDetails[] Array of

DetailedBroadcastContact

phone numbers to call and messages to play

Required



37 | P a g e



DetailedBroadcastContact Type:


phoneNumber** String The phone number to call

firstName String Optional – the first name of the

contact.

lastName String Optional – the last name of the

contact.

messageID* String Optional - The messageID of a

previously recorded message to

use for both Live Answer and

VoiceMail.

TTSText String Optional - If not specified,

defaultTTSText will be used to

create audio Message.

DetailedBroadcastAudio Type:


messageID* String Optional - The messageID of a previously

recorded message to use for both Live

Answer and VoiceMail.

TTSText String Optional - If not specified,

defaultTTSText will be used to create

audio Message.


** Can specify additional field information by separating data with the “|” character. See CommaDelimitedPhoneNumbers


CreateDetailedBroadcastResponseType






callDetailErrors Array of

BroadcastDetailError

A list of call details that failed to validate.

These details were not included in the broadcast.

BroadcastDetailError Type:


errorCode Integer Error code corresponding to the error message

errorMessage String Error message corresponding to the call detail

phoneNumber String The phone number that failed

Return/Error Codes:


-1 Unexpected Error












38 | P a g e














189 Unexpected value for broadcast type 0-voice, 1-SMS

193 A survey structure was submitted that had errors *See ExtCreateBroadcast

194 AudioID in survey structure is invalid

195 An invalid value specified for 'Throttle' must be null or integer

197 An invalid value for answerHandling was provided valid values are 0,1,2

Function: CreateNewList

Creates a new named list in the account

This function accepts 1 parameter, the request, and returns a response. Function Call: CreateNewListResponseType CreateNewList(CreateNewListRequestType myRequest)


CreateNewListRequestType



listName String The name of the List to be created Required

IsAutoReplyOn String

Def=0 No, 1=Yes If you are going to have SMS

users Opt-In to the list do you want a custom

autoreply (cost 1/2 credit per)

Optional

AutoReplyMessage String Auto reply message to SMS opt-ins if you

tie a keyword to this list. < 120 chars Optional


CreateNewListResponseType





listID Numeric String The ListID of the newly created list

listName String The list name requested

Return/Error Codes:


-1 Unexpected Error






39 | P a g e







40 | P a g e



Function: CreatePersonID

Creates a new PersonID to be used in list management

This function accepts 1 parameter, the request, and returns a response. Function Call: CreatePersonIDResponseType CreatePersonID(CreatePersonIDRequestType myRequest)


CreatePersonIDRequestType



CreatePersonIDDetailData[] personsToAdd

Array Required

CreatePersonIDDetailData Type:


PrimaryPhone String Required

FirstName String Optional


Notes String Optional

SecondaryPhone String Optional

TertiaryPhone String Optional


CreatePersonIDResponseType





ResultRecordData[]

InsertResults Array

ResultRecordData Type:


EntryNumber Int Zero Based number of the entry

PersonID Numeric String The PersonID assigned

errorMessage String Error message if problem inserting

PrimaryPhone String

FirstName String

LastName String

Notes String

SecondaryPhone String

TertiaryPhone String



41 | P a g e



Return/Error Codes:


-1 Unexpected Error








42 | P a g e



Function: CreateRecordingID

Creates a new RecordingID to be used to create audio-files for use with the API

This function accepts 1 parameter, the request, and returns a response. Function Call: CreateRecordingIDResponseType CreateRecordingID(CreateRecordingIDRequestType myRequest)


CreateRecordingIDRequestType



AudioDescription String (60 chars) The description of the recording Optional

userComment String User comments (or the text of the recording)


CreateRecordingIDResponseType





audioID String The audioID that will be assigned when the audio is recorded

MsgRecID String The code to enter when call in to record

RecordingNumber String The phone number to call in and record the message

Return/Error Codes:


-1 Unexpected Error








43 | P a g e



Function: CreateTTS

Creates a new Text to Speech message, return the audio for review and optionally save in audioLibrary

This function accepts 1 parameter, the request, and returns a response. Function Call: CreateTTSResponseType CreateTTS(CreateTTSRequestType myRequest)


CreateTTSRequestType



TTSText String The text you wish to have converted to speech Required

RequestedAudioFormat Numeric String Def=0; 0-WAV, 1-MP3 Optional

SaveInLibrary Numeric String Save in the audioLibrary Def=0; 0-No, 1-Save Optional

IsSalesIntro Numeric String Def=0; 1-Is a Sales Intro Message Optional

IsFavorite Numeric String Def=0; 1-Mark as favorite for searching Optional

AudioDescription String Description to help identify audio in library Optional


CreateTTSResponseType





byte[] TTSAudio Binary The audio stream, save to file or pass to browser to play

AudioID String Returns the audioID for reference when saved in library

Return/Error Codes:


-1 Unexpected Error







170 Required parameter 'TTSText' is missing

For additional information on formatting your TTSText message see TextToSpeech



44 | P a g e



Function: DeleteAudioLib

Deletes an audio library entry as long as it is not referenced by a pending broadcast and user has appropriate permissions

This function accepts 1 parameter, the request, and returns a response. Function Call: DeleteAudioLibResponseType DeleteAudioLib(DeleteAudioLibRequestType myRequest)


DeleteAudioLibRequestType




audioID String The audioID to delete Required


DeleteAudioLibResponseType





audioID String The audioID requested to delete

Return/Error Codes:


-1 Unexpected Error





144 An invalid AudioID was specified



186 Required parameter 'audioID' is missing

253 Cannot delete audioID entry referenced by a pending broadcast



45 | P a g e



Function: DeleteList

Deletes a list from the account

This function accepts 1 parameter, the request, and returns a response. Function Call: DeleteListResponseType DeleteList(DeleteListRequestType myRequest)


DeleteListRequestType



listID Numeric String The listID of the List to be deleted Required


DeleteListResponseType





listID String The listID attempted to delete

Return/Error Codes:


-1 Unexpected Error




172 Required parameter 'listID' is missing





46 | P a g e



Function: DeleteNumberFromBroadcast

Deletes a SINGLE number from an existing broadcast if it has *NOT* already been called.

This function accepts 1 parameter, the request, and returns a response. Function Call: DeleteNumberFromBroadcastResponseType DeleteNumberFromBroadcast(DeleteNumberFromBroadcastRequestType myRequest)


DeleteNumberFromBroadcastRequestType



broadcastID Numeric String The broadcastID to affect Required

phoneNumber Numeric String The phoneNumber to delete Required


DeleteNumberFromBroadcastResponseType





broadcastID Numeric String Requested broadcastID

phoneNumber Numeric String Requested phoneNumber

Return/Error Codes:


-1 Unexpected Error














257 Error deleting phonenumber :



47 | P a g e



Function: DeleteNumbersFromBroadcast (multiple)

Deletes MULTIPLE numbers from an existing broadcast if they have *NOT* already been called.

This function accepts 1 parameter, the request, and returns a response. Function Call: DeleteNumbersFromBroadcastResponseType DeleteNumbersFromBroadcast(DeleteNumbersFromBroadcastRequestType myRequest)


DeleteNumbersFromBroadcastRequestType



broadcastID Numeric String The broadcastID to delete numbers from Required

theNumbers[] phoneNumbers Array The phoneNumbers to delete Required

theNumbers Type:


phoneNumber Numeric String Required


DeleteNumbersFromBroadcastResponseType





DeleteResultsArray[] DeleteResults Array Status of each deletion attempt

DeleteResultsArray Type:


phoneNumber Numeric String phoneNumber to be deleted

errorCode Integer Status of delete attempt


Return/Error Codes:


-1 Unexpected Error
















48 | P a g e



Function: DeletePerson

Deletes a person from all lists

This function accepts 1 parameter, the request, and returns a response. Function Call: DeletePersonResponseType DeletePerson(DeletePersonRequestType myRequest)


DeletePersonRequestType



personID Numeric String The personID to be removed from the above list Required


DeletePersonResponseType





personID String The personID requested to be deleted

Return/Error Codes:


-1 Unexpected Error






171 Required parameter 'personID' is missing



49 | P a g e



Function: DeletePersonFromList

Deletes a person from a list

This function accepts 1 parameter, the request, and returns a response. Function Call: DeletePersonFromListResponseType DeletePersonFromList(DeletePersonFromListRequestType myRequest)


DeletePersonFromListRequestType



listID Numeric String The listID of the List to be deleted Required

personID Numeric String The personID to be removed from the above list Required


DeletePersonFromListResponseType





personID String The personId to be removed

listID String The listID to remove the person from

Return/Error Codes:


-1 Unexpected Error






171 Required parameter 'personID' is missing




50 | P a g e



Function: DeleteSchedule

Deletes a re-occurring schedule created by ScheduleWeekly or ScheduleMonthly

This function accepts 1 parameter, the request, and returns a response. Function Call: DeleteScheduleResponseType DeleteSchedule(DeleteScheduleRequestType myRequest)


DeleteScheduleRequestType



jobName String The jobName to be deleted. See GetSchedules to

Retrieve all schedules for an account Required


DeletePersonFromListResponseType





jobName String The jobName requested to be deleted

Return/Error Codes:


-1 Unexpected Error






216 Required parameter 'jobName’ is missing or contains invalid data

217 Error Deleting schedule, verify jobName with GetSchedules



51 | P a g e



Function: ExtCreateBroadcast

Extended Features

Can launch an SMS Broadcast

Can launch Voice Broadcast

Can use Text to Speech to generate messages

Can use audioID’s for the messages

Users can create custom surveys with specific option confirmation

Create message with additional information played on keypress

For more information on the OPT-IN process, see http://www.call-em-all.com or contact customer support.

ExtCreateBroadcast is the only function call required to launch a broadcast. A broadcast can include many phone numbers to call, the type

of call (survey/ announcement/SMS), and the date/time to make the calls. If the message to be sent is omitted, the return object will include

the toll free number to call and a message recording ID for the message, along with confirmation information regarding the phone

numbers supplied. End users would need to be given instructions, along with the toll free number and message recording ID to record their

audio.

This function accepts 1 parameter, the request, and returns a response. Function Call: ExtCreateBroadcastResponseType ExtCreateBroadcast(ExtCreateBroadcastRequestType myRequest)


ExtCreateBroadcastRequestType

Parameter Data Type Description /Values Required?



broadcastType Numeric String

1=Announcement;

2=Survey;

3=SMS/Text;

4=Combo SMS optIns get a text, remainder get voice

5=Combo All get voice, SMS optIns get voice and text

Required

phoneNumberSource Numeric String

1=SavedList;

2=CSV;

3=Comma Delimited String of Phone Numbers

Required


listID Numeric String The listID to send the messages to Optional

phoneNumberCSV byte[] Byte[] The CSV file containing the phone numbers to call.

Required if phoneNumberSource=2 Optional

messageID* String

Identifies the audio for the LIVE ANSWER. Pass in a

broadcastID for this parameter if you would like to

use a message from a previous broadcast or an

AudioID to use an uploaded or TTS created message

Optional

messageIDVM* String

Identifies the audio for a Voicemail ANSWER. Pass

in a broadcastID for this parameter if you would

like to use a message from a previous broadcast or

an AudioID to use an uploaded or TTS created message

Optional

launchDateTime String

Default=current date+time;

The date+time to launch the broadcast

Format: MM/DD/YYYY HH:MM AM/PM

Optional

checkCallingWindow Numeric String

Default=1;

0=Bypass calling window check;

1=Enforce calling window check;

Optional

callerID Numeric String The caller ID number to display

Default=account setting; Optional

commaDelimited

PhoneNumbers ** String

Set phoneNumberSource = 3 to use this method

instead of the byte array. Optional



52 | P a g e



smsMsg String Needed when BroadcastType = 3 SMS Optional

TTSText String The text to be spoken. OVERRIDES any specified

messageID or audioID Optional

TTSTextVM String The text to be spoken when voice mail is detected.

OVERRIDES any specified messageID or audioID Optional

Survey[] array of

Surveyoptions Array Set up custom responses for *[x] keypresses Optional

Throttle Numeric String Send no more than X simultaneous calls Optional

answerHandling Numeric String

Def=0-Automatically determine

1-Assume all answers are live

2-Assume all answers are voicemail

Optional

notifyEmail String If provided send results to the email address Optional

BroadcastTimeZone String The timezone to send the calls CST EST HST PST etc

If left empty, wil use default from account Optional



Surveyoptions Type:


action String Required

Values 0,1,2,3,4,5,6,7,8,9,N,I,M,C

0-9 match *[x] entries

N – No response

I – Invalid Response

M – Mini Menu (repeats quick options)

C – Disable Standard Prompts set

TTSTextResponse to “BYPASS” to enable

AudioID String Only set 1 of AudioID or TTSTextResponse

TTSTextResponse String Only set 1 of TTSTextResponse or AudioID

followUp string 0-hang up 1-Back to start of message


ExtCreateBroadcastResponseType

Parameter Data Type Description / Values maxCallUnitsUsed Integer

MaxMessageLength Integer

SMSBroadcastID String

errorCode Integer Returns 0 if the function was successful, otherwise it will return

an error code



SMSbroadcastID String The broadcastID to use to retrieve results for the SMS broadcast

messageRecordingID String The messageRecordingID to enter when calling the 877 to record the

message for this broadcast

tollFreeNumber String The toll free number to call to record the message

goodRecordCountOnFile Integer Good record count - populated when a file or

CommaDelimitedPhoneNumbers was passed in - 0 otherwise

badRecordCountOnFile Integer Bad record count - populated when a file or


duplicateRecrodCountOnFile Integer Duplication record count - populated when a file or


duplicateRecordCountOnFile Integer Duplication record count - populated when a file or


totalRecordCountOnFile Integer Total record count - populated when a file or


smsRecordCountOnFile Integer

voicerecordCountOnFile Integer

fileUploadErrors array of

ExtFileUploadError [] Array

A list of all errors found - populated when a file or

CommaDelimitedPhoneNumbers was passed in



53 | P a g e



ExtFileUploadError Type:


LineNumber Integer Or position number in CommaDelimitedPhoneNumbers

errorCode Integer Error code corresponding to the error message

errorMessage String Error message corresponding to the line number

PhoneNumber String The phone number that failed

Return/Error Codes:


-1 Unexpected Error















123 No good records found in phoneNumberCSV or CommaDelimitedPhoneNumbers



137 phoneNumberSource=3, but commaDelimitedPhoneNumbers is not supplied

150 Error: MessageID specified for SMS Broadcast

151 Error: MessageIDVM specified for SMS Broadcast

152 Error: A TTS Parameter was specified for an SMS Broadcast





168 Required parameter 'phoneNumberSource' is missing


189 Unexpected value for broadcast type 0-voice, 1-SMS

190 SMSMsg is blank or missing

192 Survey Options specified for SMS broadcast

193 A survey structure was submitted that had errors *See additional

194 AudioID in survey structure is invalid

195 An invalid value specified for 'Throttle' must be null or integer

197 An invalid value for answerHandling was provided valid values are 0,1,2

903

DB Exception:

Possible reasons,attempted to send to SMS phonenumbers that have

not opted in yet. See full error message for details.

* Code 193 might be folowed by a number 1 - Err both audioID and TTSTextResponse specified 2 – Err both AudioID and TTSTextResponse are blank 3 – Err followUp has invalid value 0,1,2 4 – Err TTSTextResponse is blank, but audioID does not contain a properly formatted audioID 5 – Err Action contains an invalid value only accepts 1,2,3,4,5,6,7,8,9,0,N,I,M,C



54 | P a g e



How to Customize a Survey or provide information in response to Keypresses

{ "username": "URUSERNAME" "pin": "URPIN" "TTSText": "Hello this is Market Makers with the latest Job opportunities, Please listen to the following options to hear about an opportunity in your field, for Electrical Jobs press star 1, for Janitorial Jobs press star 2, for Clerical Jobs press star 3, for Construction Jobs press star 4 " "TTSTextVM": "Sorry we missed you, this is Market Makers, we have new job postings visit us at http://MarketMakers.info" "answerHandling": "0" <== 0 - System attempts to decide, 1 - Assume voice mail "broadcastName": "Job Opportunities 8-14-2012" "broadcastType": "2" <== 1 is announcement, 2 is survey and will retrurn the lat option the person selected "callerID": "URCALLERID" <== If left empty or not provided, will use default callerID from account "checkCallingWindow": "1" <== Default = 1, to honor account calling window, 0 - Bypass checks "phoneNumberSource": "3" <== How we are passing number to be called 1 - listID, 2 - Binary encoded CSV/Excel, 3 - CommaDelimitedPhoneNumbers "commaDelimitedPhoneNumbers": "7145554574,7145557362" <== The numbers to call "launchDateTime": "08/14/2012 9:00:00" <== When to start making calls "messageID": "XXNNN" <== Instead of using TTS you can specify an AudioID to play "messageIDVM": "XXNNN" <== Instead of using TTS you can specify an AudioID to play "notifyEmail": "[email protected]" <== Where to send notification emails "survey": [ { "AudioID": null "TTSTextResponse": "BYPASS" <== This combined with Action "C" overrides system prompts "action": "C" "followUp": "0" <== ignored on Action "C" }, { "AudioID": null "TTSTextResponse": "I did not receive an answer" <== What to say if no response Action "N" "action": "N" "followUp": "1" <== 0 means hang up after action, 1 means go back to menu }, { "AudioID": null "TTSTextResponse": "That is an invalid option" <== Action "I" invalid entry "action": "I" "followUp": "1" <== 0 means hang up after action, 1 means go back to menu },



55 | P a g e



{ "AudioID": null "TTSTextResponse": " for Electrical Jobs press star 1, for Janitorial Jobs press star 2, for Clerical Jobs press star 3, for Construction Jobs press star 4 " <= Action "M" Mini-Menu "action": "M" "followUp": "1" <== 0 means hang up after action, 1 means go back to menu }, { "AudioID": null "TTSTextResponse": "We have need of 2 Journey men electricians for the next 2 weeks working in the downtown Dallas area. If you are interested call us at 714-555-1234 again that number is 714-555-1234" <== Action "1" when *1 is pressed "action": "1" "followUp": "0" <== 0 means hang up after action, 1 means go back to menu }, { "AudioID": null "TTSTextResponse": "We need 4 people to work the Bentely Hi-rise, this is an ongoing position, is you are interested call us at 714-555-1234 again that number is 714-555-1234" <== Action "2" when *2 is pressed "action": "2" "followUp": "0" <== 0 means hang up after action, 1 means go back to menu } ] "throttle": "" }



56 | P a g e



Function: GetAccountkeywords Return all keywords for the account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAccountKeywordsResponseType GetAccountKeywords(GetAccountKeywordsRequestType myRequest)


GetAccountkeywordsRequestType




GetAccountKeywordsResponseType





OptOuts array of

OptOutDetail[] array The lists configured in the account

OptOutDetail Type:


PhoneNumber String

DateAdded String

Firstname String

LastName String

Return/Error Codes: Code Description 0 Function executed successfully

-1 Unexpected Error








57 | P a g e



Function: GetAccountOptOuts Return all opted out phone numbers for the account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAccountOptOutsResponseType GetAccountOptOuts(GetAccountOptOutsRequestType myRequest)


GetAccountOptOutsRequestType



startDate String The startDate and Time to filter by MM/DD/YYYY HH:MM Optional

stopDate String The stopDate and Time to filter by MM/DD/YYYY HH:MM Optional


GetAccountOptOutsResponseType





OptOuts array of

OptOutDetail[] array The lists configured in the account

OptOutDetail Type:


PhoneNumber String

DateAdded String

Firstname String

LastName String


-1 Unexpected Error








58 | P a g e



Function: GetAccountStatusValues

Enumeration of Account status values and descriptions

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAccountStatusResponseType GetAccountStatusValues(GetAccountStatusRequestType myRequest)


GetAccountStatusRequestType




GetAccountStatusResponseType





StatusContents array of

StatusDetailData[] Array Account statuses and description

StatusDetailData Type:


AccountStatus Numeric String

Description String

Return/Error Codes:


-1 Unexpected Error








59 | P a g e



Function: GetAllBroadcastStatus

Return status of all broadcast of type selected with optional filtering and sorting

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAllBroadcastStatusResponseType GetAllBroadcastStatus(GetAllBroadcastStatusRequestType myRequest)


GetAllBroadcastStatusRequestType



Status Numeric String

Default = 0–Active

1-Completed (back max of 90 days)

2-Both Active and Completed

Optional

broadcastType Numeric String

Default = 0-Voice

1-SMS

2-Both

Optional

sortField Numeric String Default = 0-Broadcast StartDate Desc

1-Broadcast CreateDate Desc Optional

startDate* String The startDate and Time to filter by

MM/DD/YYYY HH:MM Optional

stopDate* String The stopDate and Time to filter by


*Filtering is based on what value sortField is set to, default is Broadcast StartDate


GetAllBroadcastStatusResponseType





BroadCastContents array of

BroadcastDetailData[] Array The returned broadcast data

BroadcastDetailData Type:


actualCallUnitsUsed String

maxCallUnitsUsed String

startDate String

startTime String

broadcastID String

broadcastName String

status String

completedCalls String

notCompleted String

totalcalls String

createTimeStamp String

livePerson String

voiceMail String

busyNA String

callerIDNumber String

invalidNumber String



60 | P a g e



notCompleted String

broadcastType String Possible values, "SMS" or "Voice"

isActive String

"1" Broadcast is active/current

"0" Broadcast is completed/cancelled

Return/Error Codes:


-1 Unexpected Error








61 | P a g e



Function: GetAudioLib

Returns audio library entries matching required parameters

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAudioLibResponseType GetAudioLib(GetAudioLibRequestType myRequest)


GetAudioLibRequestType




isSalesIntro String Blank/Null = Don't Care [0=false, 1=true] Optional

isAudioTTS String Blank/Null = Don't Care [0=false, 1=true] Optional

hasSalesIntro String Blank/Null = Don't Care [0=false, 1=true] Optional

favorite String Blank/Null = Don't Care [0=false, 1=true] Optional

messageType String Blank/Null = Don't Care [ the message type] Optional


GetAudioLibResponseType




errorMessage The error message corresponding with the error code

GetAudioLibContents array of

GetAudioLibDetailData[] Array The Audio Library entries matching criteria

GetAudioLibDetailData Type:


audioID String

audioDescription String

userComment String

isSalesIntro Boolean

isAudioTTS Boolean

audioLength Int32

dateAdded Boolean

dateLastUsed Datetime

hasSalesIntro Datetime

favorite Boolean

messageType Short

Active Short

Return/Error Codes:


-1 Unexpected Error




62 | P a g e










63 | P a g e



Function: GetAudioLink DEPRECATED (Broadcast ID)

Retrieve the audio used for a particular broadcast

DEPRECATED (see RetrieveAudio)

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAudioLinkResponseType GetAudioLink(GetAudioLinkRequestType myRequest)


GetAudioLinkRequestType

Parameter Data Type Description / Values Required? Username Numeric String The CEA Username of the account Required


broadcastID Numeric String The broadcastID you want the Audio from Required


GetAudioLinkResponseType





BinaryMessage byte[] Binary The audio stream for the broadcasts message

BinaryVmailMessage

byte[] Binary

The audio stream for the broadcasts voice mail message if

one was recorded

Return/Error Codes:


-1 Unexpected Error





131 BroadcastID was not found






64 | P a g e



Function: GetAudioLinkMP3 DEPRECATED (Broadcast ID)

Retrieve the audio saved for a particular broadcast (save binary responses as .mp3 file extension to play)


This function accepts 1 parameter, the request, and returns a response. Function Call: GetAudioLinkMP3ResponseType GetAudioLinkMP3(GetAudioLinkMP3RequestType myRequest)


GetAudioLinkMP3RequestType





GetAudioLinkMP3ResponseType






BinaryVmailMessage byte[] Binary The audio stream for the broadcasts voice mail message if

one was recorded

Return/Error Codes:


-1 Unexpected Error











65 | P a g e



Function: GetAudioLinkWAV DEPRECATED (Broadcast ID)

Retrieve the audio saved for a particular broadcast (save binary responses as .wav file extension to play)


This function accepts 1 parameter, the request, and returns a response. Function Call: GetAudioLinkWAVResponseType GetAudioLinkWAV(GetAudioLinkWAVRequestType myRequest)


GetAudioLinkWAVRequestType





GetAudioLinkWAVResponseType






BinaryVmailMessage byte[] Binary The audio stream for the broadcasts voice mail message if

one was recorded

Return/Error Codes:


-1 Unexpected Error











66 | P a g e



Function: GetAvailableCreditCardTypes

Enumeration of Accepted Credit card enumerations and descriptions

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAvailableCreditCardTypesResponseType

GetAvailableCreditCardTypes(GetAvailableCreditCardTypesRequestType myRequest)


GetAvailableCreditCardTypesRequestType




GetAvailableCreditCardTypesResponseType





CardContents array of

CardDetailData[] Array The accepted credit card types and description

CardDetailData Type:


CCType Numeric String

CCDescription String

Return/Error Codes:


-1 Unexpected Error









67 | P a g e



Function: GetAvailableGroupCodes

Enumeration of Accepted Credit card enumerations and descriptions

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAvailableGroupCodesResponseType GetAvailableGroupCodes(GetAvailableGroupCodesRequestType myRequest)


GetAvailableGroupCodesRequestType




GetAvailabeGroupCodesResponseType





GroupContents array of

GroupDetailData[] Array The Group codes available for use.

GroupDetailData Type:


GroupCode Numeric String

GroupDescription String

Return/Error Codes:


-1 Unexpected Error









68 | P a g e



Function: GetAvailableLists

Return the lists available in the account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetAvailableListsResponseType GetAvailableLists(GetAvailableListsRequestType myRequest)


GetAvailableListsRequestType




GetAvailableListsResponseType





lists array of

ListDetail[] Array The lists configured in the account

ListDetail Type:


ListName String Descriptive name of the list

ListID Int64 The ListID (used to manipulate lists)

PhoneNumberCount Int32 Count of phonenumbers in list

SMSName String Opt In Keyword for List

AutoReplyMessage String Reply to opting in

IsAutoReplyOn String 0-false; 1-true Send AutoReplyMessage or not

Return/Error Codes:


-1 Unexpected Error









69 | P a g e



Function: GetBroadcastResult

GetBroadcastResult will retrieve the results of a broadcast. Results may be returned for in-progress and/or completed broadcasts for up to 90 days from the date of broadcast completion. Call-Em-All recommends and requests that our clients store this information in their database for future access, and to eliminate repetitive demands for large volumes of information. Requests will return either summary information or detailed (call-by-call) results.

Function Call:

GetBroadcastResultResponseType GetBroadcastResult (GetBroadcastResultRequestType myRequest)


GetBroadcastResultRequestType

Parameter Data Type Description Required?

Username Numeric String The CEA Username of the account Required


broadcastID Numeric String The broadcastID to query Required

getBroadcastSummary String Default=0, 0=Do not return summary, 1=Return summary Optional

getBroadcastDetails String Default=0, 0=Do not return details, 1=Return

broadcast details Optional

surveyResultFilter String

Only used when getBroadcastDetails=1, 1=Only return

results with a specific survey result, *=only return

calls with a survey result

Optional

callResultFilter String Only checked when getBroadcastDetails=1, Only return

calls with a certain call result Optional

Valid values for callResultFilter for VOICE Broadcast:

Value CallType

* All Results

0 No Result Yet

1 Live Answer

2 Busy Signal

3 Operator Intercept

4 Ring No Answer

5 (Not Used)

6 Do Not Call

7 Voicemail

8 Calling Window Expired

9 Canceled

Valid values for callResultFilter for an SMS Broadcast:

Value CallType

* All Results

0 Not Sent

1 Sent to Carrier

2 Sent to Handset

3 Cancelled

4 Expired

5 Not Authorized

6 Pending Authorization

7 Carrier Not Available

8 Not mobile device

9 Opted out

10 Error

11 Rejected Billing

12 Rejected Handset

13 Rejected Carrier

14 Rejected Content



70 | P a g e




GetBroadcastResultResponseType




errorMessage String The error message cooresponding with the error code

broadcastStatus Int16 The current status of the broadcast

broadcastStatusName String The text equivelant of the broadcastStatus

completedCalls Int32 The current number of Completed calls for the broadcast

liveAnswerResults Int32 The current number of Live Answer calls for the broadcast

voiceMailResults Int32 The current number of Voice Mail calls for the broadcast

busyNoAnswerResults Int32 The current number of Busy / No Answer calls for the broadcast

invalidNumberResults Int32 The current number of Invalid Number calls for the broadcast

broadcastDetails Array CallDetail[] Only returned when getBroadcastDetails=1

broadcastName String Added when available

audioMessage String Added when available

AudioMessageVM String Added when available

broadcastID String Added to help identify responses via Async calls

SMSMsg String If available returns the SMS text that was specified

broadcastStatus:

broadcastStatus broadcastStatusName

0 Pending Message

1 Message Recorded

2 Generating Detail Records

3 Broadcasting

4 Complete

5 Canceled

6 Awaiting Authorization

7 Authorization Declined - Needs Sales Intro

8 Authorization Approved

9 Processing

10 Expired

11 Authorization Declined - Spam

12 Authorization Declined - Bad Recording Quality

13 Message Recorded - Update Window

callDetail Type:


phoneNumber Phonenumber or SMS number

firstName If available the first name

lastName If available the last name

numberOfAttempts How many time attempted

lastCallTime Date/Time of last attempt

callResult Valid values listed in CallResultFilter table above.

callResultName Valid values listed in CallResultFilter table above.

surveyResult If a survey what digit they replied with

Return/Error Codes:


-1 Unexpected Error




71 | P a g e






124 Unexpected value for getBroadcastSummary; Expecting 0 or 1

125 Unexpected value for getBroadcastDetails; Expecting 0 or 1

126 Unexpected value for surveyResultFilter; Expecting

*,0,1,2,3,4,5,6,7,8, or 9

127 Unexpected value for callResultFilter; Expecting 0,1,2,3,4,5,6,7,8,

or 9

128 Cannot filter results by both surveyResultsFilter and

callResultFilter. Only pass in one or the other

129 getBroadcastDetails=1, but neither callResultFilter or

surveyResultFilter is supplied

130 getBroadcastDetails=0, but either callResultFilter or

surveyResultFilter is supplied

131 broadcastID not found






72 | P a g e



Function: GetBroadcastStatusValues

Enumeration of Broadcast status values and descriptions

This function accepts 1 parameter, the request, and returns a response. Function Call: GetBroadcastStatusValuesResponseType GetBroadcastStatusValues(GetBroadcastStatusValuesRequestType

myRequest)


GetBroadcastStatusValuesRequestType





GetBroadcastStatusValuesResponseType




errorMessage String The error message corresponding with the error

code


BroadcastStatusValuesDetailData[] Array Broadcast Statuses and descriptions

BroadcastStatusValuesDetailData Type:


AccountStatus String

Description String

Return/Error Codes:


-1 Unexpected Error









73 | P a g e



Function: GetCallBalance

History of balance changes for the account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetCallBalanceResponseType GetCallBalance(GetCallBalanceRequestType myRequest)


GetCallBalanceRequestType




startDate String The startDate and Time to filter by


stopDate String The stopDate and Time to filter by



GetCallBalanceResponseType





code

GetCallBalanceContents array of

GetCallBalanceDetailData[] Array

The balance changes recorded against the

account

GetCallBalanceDetailData Type:


CreditTimeStamp String

NumberCallsCredited String

CreditType String

Notes String

ChargeHistoryID String

FirstName String

LastName String

Return/Error Codes:


-1 Unexpected Error









74 | P a g e



Function: GetCallResultValues

Enumeration of Broadcast status values and descriptions

This function accepts 1 parameter, the request, and returns a response. Function Call: GetCallResultValuesResponseType GetCallResultValues(GetCallResultValuesRequestType myRequest)


GetCallResultValuesRequestType





GetCallResultValuesResponseType





code


CallResultValuesDetailData[] Array Broadcast Statuses and descriptions

GetCallResultValuesDetailData Type:


CallResult String

Description String

Return/Error Codes:


-1 Unexpected Error









75 | P a g e



Function: GetChargeHistory

History of charges for the account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetChargeHistoryResponseType GetChargeHistory(GetChargeHistoryRequestType myRequest)


GetChargeHistoryRequestType









GetChargeHistoryResponseType





GetChargeHistoryContents array of

GetChargeHistoryDetailData [] Array The charges recorded against the account

GetChargeHistoryDetailData Type:


ChargeTimeStamp String

TotalAmountCharged String

Notes String

TransactionType String

ConfirmationNumber String

SalesTaxCharged String

ReferenceCode String

CCType String

CCDisplay String

FirstName String

Lastname String

Expiration String

SubscriptionLevel String

PartialCost String

PartialCredit String

Return/Error Codes:


-1 Unexpected Error





76 | P a g e






Function: GetListContents

Return the contents of a specified list, see GetAvailableLists to retrieve all listID’s and name and list counts to help calculate paging.

This function accepts 1 parameter, the request, and returns a response. Function Call: GetListContentsResponseType GetListContents(GetListContentsRequestType myRequest)


GetListContentsRequestType




ListID Numeric String The list ID you want the contents for

(default is 0 == everyone) Optional

pageSize Numeric String How many records to return (Def=100) Optional

whatPage Numeric String If specify pagesize, what result page do you want.

If blank defaults to page 1 Optional


GetListContentsResponseType





ListContents array of

ListDetailData[] Array The lists configured in the account

ListDetailData Type:


PersonID Numeric String

PrimaryPhone Numeric String

Firstname String

LastName String

Notes String

SecondaryPhone Numeric String

TertiaryPhone Numeric String


-1 Unexpected Error







250 pageSize contains an invalid value; allowed values 1 - 100; suggest values 20 - 50

251 whatPage contains an invalid value; acceptable values 1 - N

252 pageSize specified, but whatPage is null



77 | P a g e



Function: GetListIDByName

Return the listID with the specified name

This function accepts 1 parameter, the request, and returns a response. Function Call: GetListIDByNameResponseType GetListIDByName(GetListIDByNameRequestType myRequest)


GetListIDByNameRequestType



listName String The listName to look up (exact match) Required


GetListIDByNameResponseType





listID String The listID matching the name

Return/Error Codes:


-1 Unexpected Error









78 | P a g e



Function: GetListsByPersonID

Return the listIDs associated with the specified PersonID

This function accepts 1 parameter, the request, and returns a response. Function Call: GetListsByPersonIDResponseType GetListsByPersonID(GetListsByPersonIDRequestType myRequest)


GetListsByPersonIDRequestType



personID Numeric String The personID to query what lists belong to Required


GetListsByPersonIDResponseType





code

GetListsByPersonIDListDetail[]

lists

Array

GetlistsByPersonIDListDetail Type:


ListName String

ListID Int64

PhoneNumberCount Int32

SMSName String

AutoReplyMesage String

IsAutoReplyOn String 0-No 1-Yes

Return/Error Codes:


-1 Unexpected Error









79 | P a g e



Function: GetOptOutList

Return all opted out phone numbers for the account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetOptOutListResponseType GetOptOutList(GetOptOutListRequestType myRequest)


GetOptOutListRequestType







GetOptOutListResponseType





code

GetOptOutListContents array of

GetOptOutListDetailData[] Array The lists configured in the account

GetOptOutListDetailData Type:


PhoneNumber Numeric String

DateAdded String

Firstname String

LastName String

Return/Error Codes:


-1 Unexpected Error








80 | P a g e



Function: GetPersonIDDetails

List all personID’s that a phone number is associated with

This function accepts 1 parameter, the request, and returns a response. Function Call: GetPersonIDDetailsResponseType GetPersonIDDetails(GetPersonIDDetailsRequestType myRequest)


GetPersonIDDetailsRequestType




personID String The personID to query Required


GetPersonIDDetailsResponseType




errorMessage String The error message corresponding with the

error code

GetPersonIDDetailsListDetailData[]

ListContents

Array The personID Details

GetPersonIDDetailsListDetailData Type:



PrimaryPhone String

FirstName String

LastName String

Notes String



Return/Error Codes:


-1 Unexpected Error








81 | P a g e



Function: GetPersonIDsByPhone

List all personID’s that a phone number is associated with

This function accepts 1 parameter, the request, and returns a response. Function Call: GetPersonIDsByPhoneResponseType GetPersonIDsByPhone(GetPersonIDsByPhoneRequestType myRequest)


GetPersonIDsByPhoneRequestType




phoneNumber String The phonenumber to query Required


GetPersonIDsByPhoneResponseType





error code

GetPersonIDsByPhoneListDetailData[] ListContents

Array The lists configured in the account

GetPersonIDsByPhoneListDetailData Type:



PrimaryPhone String

FirstName String

LastName String

Notes String



Return/Error Codes:


-1 Unexpected Error








82 | P a g e



Function: GetPhoneNumberHistory

Retrieve all call details for a particular phone number can be filtered by start/stop date

This function accepts 1 parameter, the request, and returns a response. Function Call: GetPhoneNumberHistoryResponseType GetPhoneNumberHistory(GetPhoneNumberHistoryRequestType myRequest)


GetPhoneNumberHistoryRequestType




phoneNumber String The phonenumber to query Required




GetPhoneNumberHistoryResponseType





error code

GetPhoneNumberHistoryDetailData[] ListContents

Array The lists configured in the account

GetPersonIDsByPhoneListDetailData Type:


PrimaryPhone String

CallResultDesc String

CallBroadcastID String

BroadcastName String

AudioMessage String

NumberOfAttempts String

LastCallDate String

BroadcastType String

SurveyResult String

Return/Error Codes:


-1 Unexpected Error








83 | P a g e



Function: GetSchedules

List all schedules that exist under an account

This function accepts 1 parameter, the request, and returns a response. Function Call: GetSchedulesResponseType GetSchedules(GetSchedulesRequestType myRequest)


GetSchedulesRequestType





GetSchedulesResponseType





code

GetSchedulesDetailData[] ScheduleContents

Array The different scheduled re-occurring

broadcasts that exist

GetSchedulesDetailData Type:


jobName String

Use jobName when calling DeleteSchedule to

delete a re-occurring broadcast

occurs String Text description of when the schedule runs

beginDate String (date) When schedule is active/starts

endDate String (date) When schedule stops

durationMinutes String (int) Can specify it to run for X hours

intervalMinutes String (int) How often to wake up and run

mostRecentRunTime String (date+time) When schedule last ran (or “Never”)

nextRunTime String (date+time) When will next run (or “Never”)

status String Active / Disabled

scheduleName String

callerID Numeric string

audioID String

listID Numeric string

notificationFlag String

SMSMessageText String

broadcastType String (int)



84 | P a g e



Return/Error Codes:


-1 Unexpected Error








85 | P a g e



Function: GetSMSInbox

Return results, responses from users sms messages

This function accepts 1 parameter, the request, and returns a response. Function Call: GetSMSInboxResponseType GetSMSInbox(GetSMSInboxRequestType myRequest)


GetSMSInboxRequestType




messageCounter Numeric String Pass in the most recent inboxID received and

system will return all messages since. Optional

status String Default = *-All types, 0-unread, 1-read, 2-deleted Optional





phoneNumber String Retrieve only records that match Optional


GetSMSInboxResponseType





code

GetSMSInboxContents array of GetSMSInboxDetailData[]

Array The inbox details

GetSMSInboxDetailData Type:


inboxID Numeric String Unique ascending ID

messageType

Numeric String

SmsOptIn = 0, SmsOptOut = 1, SystemMsg = 2, BcSent = 3, BcReply = 4, HardReplyBc = 5, HardReplyNoBc = 6

status

Numeric String

NotRead = 0, Read = 1, Deleted = 2

subject String

body String

broadcastID String

phoneNumber Numeric String

firstName String

lastName String

received Date String



86 | P a g e



lastUpdated Date String

Return/Error Codes:


-1 Unexpected Error








87 | P a g e



Function: GetSMSOptIns

Return all phone numbers that have opted in for SMS, or return only those for a particular listID

This function accepts 1 parameter, the request, and returns a response. Function Call: GetSMSOptInsResponseType GetSMSOptIns(GetSMSOptInsRequestType myRequest)


GetSMSOptInsRequestType




listID Numeric String The list ID you want the contents for

(default is 0 == everyone) Optional






GetSMSOptInsResponseType





code

GetSMSOptInsContents array of

GetSMSOptinsDetailData[] Array The lists configured in the account

GetSMSOptInsDetailData Type:


personID Numeric String

listID Numeric String

PhoneNumber Numeric String

DateAdded Date String

Firstname String

LastName String

Return/Error Codes:


-1 Unexpected Error








88 | P a g e



Function: GetSMSResultValues

Enumeration of SMS Result values and descriptions

This function accepts 1 parameter, the request, and returns a response. Function Call: GetSMSResultValuesResponseType GetSMSResultValues(GetSMSResultValuesRequestType myRequest)


GetSMSResultValuesRequestType





GetSMSResultValuesResponseType





code

GetSMSResultValues array of

GetSMSResultValuesDetailData[] Array Broadcast Statuses and descriptions

GetSMSResultValuesDetailData Type:


SMSResult String

Description String

Return/Error Codes:


-1 Unexpected Error









89 | P a g e



Function: InsertCustomCall

This function is used to create a single call with a specific message at a specific time.

This function accepts 1 parameter, the request, and returns a response. Function Call: InsertCustomCallResponseType InsertCustomCall(InsertCustomCallRequestType myRequest)


InsertCustomCallRequestType


Username Numeric

String The CEA Username of the account Required

Pin Numeric

String The CEA Pin of the account Required

phoneNumber Numeric

String The phone number to call Required

messageID

* also supports audioID

Numeric

String

The Broadcast ID corresponding with the message to

play on the call Optional

sourceURL The URL of the caller or Program name Required

checkMaxPhoneCount Numeric

String

Default=1; 0=Bypass max phone number check;

1=Enforce max phone number check Optional

maxPhoneCount Numeric

String

Default=5; The maximum number of times a phone

number can be called; Only checked if

checkMaxPhoneCount=1; Optional

checkCallingWindow Numeric

String

Default=1; 0=Bypass calling window check; 1=Enforce

calling window check; Optional

launchDateTime String Default=current date and time; The date and time to

launch the call in MM/DD/YYYY HH:MM AM/PM format Optional

callerID Numeric

String Default=account setting; The caller ID to display Optional

TTSText String If specified, TTS will be used to create Message Optional

* An audioID is generated when you upload Audio using ProvideAudio or when you specify to save the results

in CreateTTS


InsertCustomCallResponseType





Return/Error Codes:


-1 Unexpected Error

101 Phone number does not contain 10 digits

102 Phone number is not in the continental US, Hawaii, or Canada

103 Phone number is on the Call-em-all opt out list






90 | P a g e





109 MaxPhoneCount must be >= 1

110 Phone number exceeded call limit

111 Current local time is outside of your calling window

112 Unexpected value for checkMaxPhoneCount; Expecting 0 or 1.

113 Unexpected value for maxPhoneCount; maxPhoneCount must be >= 1


119 Datetime must be in MM/DD/YYYY HH:MM AM/PM format







164 Required parameter 'messageID' is missing

165 Required parameter 'sourceURL' is missing



91 | P a g e



Function: InsertOptOut

Inserts a number into an account's opt out registry

This function accepts 1 parameter, the request, and returns a response. Function Call: InsertOptOutResponseType InsertOptOut(InsertOptOutRequestType myRequest)


InsertOptOutRequestType




phoneNumber Numeric String The phone number to be added to the opt out registry Required


InsertOptOutResponseType





Return/Error Codes:


-1 Unexpected Error

101 Phone number does not contain 10 digits









92 | P a g e



Function: LinkKeywordToList

Link a top level SMS keyword to a list

This function accepts 1 parameter, the request, and returns a response. Function Call: LinkKeywordToListResponseType LinkKeywordToList(LinkKeywordToListRequestType myRequest)


LinkKeywordToListRequestType



listID String The listID to link the keyword to Required

keyword String The keyword to link to the list

(Verify availability with CheckKeywordAvailable) Required


LinkKeywordToListResponseType





Return/Error Codes:


-1 Unexpected Error








188 Required parameter 'keyword' is missing

196 Requested keyword is not available

201 Keywords must be between 3 and 20 digits alpha-numeric and dash only



93 | P a g e



Function: ProvideAudio

Upload an audio file to your audio library for use in future broadcasts

This function accepts 1 parameter, the request, and returns a response. Function Call: ProvideAudioResponseType ProvideAudio(ProvideAudioRequestType myRequest)


ProvideAudioRequestType




AudioType Numeric String

Def=0; 0=WAV, 1=MP3, 2=AVI

3=WMA;WMV;ASF;MPG;AIF;AU;SND;MID;RMI;OGG;FLAC;

CDA;AC3;DTS;MKA;MKV;MPC;M4A;AAC;MPA;

MP2;M1A;M2A

Optional

Byte[]

BinaryMessage Binary The raw audio file in the specified format Required

AudioDescription String A description of the Audio Reccomended


ProvideAudioResponseType





AudioID String The audioID for future reference in creating broadcasts

AudioLength Integer The length of the uploaded audio in seconds

Return/Error Codes:


-1 Unexpected Error





141 Empty BinaryMessage not allowed

142 Invalid AudioType specified





94 | P a g e



Function: RenameList

Changes a list’s name

This function accepts 1 parameter, the request, and returns a response. Function Call: RenameListResponseType RenameList(RenameListRequestType myRequest)


RenameListRequestType



listID Long The listID of the List to be renamed Required

newListName Numeric String The new list name Required


RenameListResponseType





listID Long The listID attempted to rename

Return/Error Codes:


-1 Unexpected Error








218 Required parameter 'newListName' is missing



95 | P a g e



Function: RetrieveAudio

Retrieve an audio file from your audio library

This function accepts 1 parameter, the request, and returns a response. Function Call: RetrieveAudioResponseType RetrieveAudio(RetrieveAudioRequestType myRequest)


RetrieveAudioRequestType




AudioID String The AudioID you want the audio from Required

AudioFormat Numeric String Def=0; 0=WAV, 1=MP2 Optional


RetrieveAudioResponseType





BinaryFile Byte[] Binary save this to disk with requested extension

Return/Error Codes:


-1 Unexpected Error








191 Invalid audioformat specified 0=WAV, 1=MP3



96 | P a g e



Function: RetrieveRecordingIDs

Retrieve recordings ID's that have not yet had the message recorded

This function accepts 1 parameter, the request, and returns a response. Function Call: RetrieveRecordingIDsResponseType RetrieveRecordingIDs(RetrieveRecordingIDsRequestType myRequest)


RetrieveRecordingIDsRequestType




RetrieveRecordingIDsResponseType





tbAudioRecordings [] ActiveRecordings

Array

tbAudioRecordings Type:


MsgRecID Long Number to enter when calling in to

record the message

AccountID Long Internal Usage

UserID Long Internal Usage

DateCreated DateTime Date the recording ID was created

audioID String The audioID that will be assigned

when the message is recorded

RecordingStatus Byte Internal Usage

PhoneNumber String Number to dial to record message

lastUpdated DateTime Internal Usage

DetGenGUID GUID Internal Usage

AudioDescription String What the user entered when the

recording request was created

userComment String What the user entered when the

recording request was created

Return/Error Codes:



97 | P a g e




-1 Unexpected Error








98 | P a g e



Function: ScheduleDaily

Schedule a broadcast to a particular Group/ListID to occur on a daily basis

This function accepts 1 parameter, the request, and returns a response. Function Call: ScheduleDailyResponseType ScheduleDaily(ScheduleDailyRequestType myRequest)


ScheduleDailyRequestType




BroadcastName String BroadcastName Required

CallerID String CallerID to display, defaults to number on

account Optional

AudioID String AudioID of the message/recording to use Required

ListID String The listID to send the messages to Required

StartDate String

Use MM/DD/YYYY format

The day the recurring message starts

Required

StopDate String


The day the recurring message stops

Required

StartTime String

HH:MM Use 24 hour clock (user local TZ)

12 – noon 23:59 - midnight

The time of day to make the call

Required

ReOccursXDays String Default=1, can can be 2 (every other day) or

3 (every three days)4..5..6.. etc Required

AdvancedFlag String To Use advanced features set = 1, 0=def Optional

RepeatEvery String

Use an integer number

ie

15 = 15 minutes

37 = 37 minutes

90 = 1 hour and 30 minutes

Nummber of minutes after first call is made

to call again. Be careful system will re-try

if no-answer on a 5-15-15-15 schedule by

default so repeats can be annoying

Only used if Advanced is set = 1

Optional

RepeatUntil String The time to stop repeating the call

Only used if Advanced is set = 1 Optional

SendEmailOnCompletion String

(0/1) Depends on account, set = 1 if you

Want an email when your scheduled call is

sent, default = 0

Optional

SMSText String Needed for combo broadcasts

BroadcastType = 3,4 or 5 Optional

BroadcastType Numeric string

1-default Voice Only

3-SMS Only

4-SMS or Voice

5-SMS and VOICE

commaDelimitedPhoneNumbers ** String Comma delimited list of numbers to call




99 | P a g e




ScheduledailyResponseType





Return/Error Codes:


-1 Unexpected Error








267 Required Data Missing or incorrect format :

268 Failed to Initialize Scheduler

269 Repeat Until time is less than or equal to Start time

270 Error Parsing StartTime and or Duration

271 Error during CreateTask

272 Error creating Trigger

273 Error processing days of week



100 | P a g e



Function: ScheduleWeekly

Schedule a broadcast to a particular Group/ListID to occur on a weekly basis

This function accepts 1 parameter, the request, and returns a response. Function Call: ScheduleWeeklyResponseType ScheduleWeekly(ScheduleWeeklyRequestType myRequest)


ScheduleWeeklyRequestType




BroadcastName String BroadcastName Required

CallerID String CallerID to display, defaults to number on

account Optional

AudioID String AudioID of the message/recording to use Required

ListID String The listID to send the messages to Required

StartDate String


The day the recurring message starts

Required

StopDate String


The day the recurring message stops

Required

StartTime String

HH:MM Use 24hr clock(users local timezone)

12 – noon 23:59 - midnight

The time of day to make the call

Required

ReOccursXWeeks String Default=1, can can be 2 (every other week) or

3 (every three weeks)4..5..6.. etc Required

DaysOfWeek String

1=true

0=false

Delimiter is a “:”

The system week starts on Sunday

Call only on Sunday, Monday, Tuesday

1:1:1:0:0:0:0

Call only on Wednesday and Saturday

0:0:0:1:0:0:1

Required

AdvancedFlag String To use advanced features set = 1, 0=def Optional

RepeatEvery String

Use an integer number

15 = 15 minutes

37 = 37 minutes

90 = 1 hour and 30 minutes

Nummber of minutes after first call is made

to call again. Be careful system will re-try

if no-answer on a 5-15-15-15 schedule by

default so repeats can be annoying

Only used if Advanced is set = 1

Optional



101 | P a g e



RepeatUntil String

The time to stop repeating the call

Only used if Advanced is set = 1 Optional

SendEmailOnCompletion String

(0/1) Depends on account, set = 1 if you want

an email when your scheduled call is sent,

default = 0

Optional

SMSText String Needed for combo broadcasts

BroadcastType = 3,4 or 5 Optional

BroadcastType Numeric string

1-default Voice Only

3-SMS Only

4-SMS or Voice

5-SMS and VOICE

Optional

Has

default


ScheduledailyResponseType





Return/Error Codes:


-1 Unexpected Error








267 Required Data Missing or incorrect format :

268 Failed to Initialize Scheduler

269 Repeat Until time is less than or equal to Start time

270 Error Parsing StartTime and or Duration

271 Error during CreateTask

272 Error creating Trigger

273 Error processing days of week



102 | P a g e



Function: SendOptInvitation

Send an invitaion to an SMS number for them to join a group

This function accepts 1 parameter, the request, and returns a response. Function Call: SendOptInvitationResponseType SendOptInvitation(SendOptInvitationRequestType myRequest)


SendOptInvitationRequestType




firstName String Persons first name Optional

lastName String Persons last name Optional

invitePhoneNumber Numeric String The SMS capable phone number to invite Required

keyword String The keyword you are inviting them to join Required

message String

60 chars or less description of the group,

do *not* put in join instructions, they will

be added by system

Optional

YisOK String

Def=0 - Require TXT back of Keyword

1 – Allow “Y” response if no other opt-ins

Have been sent or are pending


SendOptInvitationResponseType





response Integer The response from the Opt-In sub-system

keyword String The keyword that was acted upon

Message String The system generated portion of the SMS sent, prepended to

your message before being sent

Return/Error Codes:


-1 Unexpected Error








191 Invalid audioformat specified 0=WAV, 1=MP3



103 | P a g e



Function: UpdateAccountInfo

Updates basic account information (name, address, city, state, zip, company)

This function accepts 1 parameter, the request, and returns a response. Function Call: UpdateAccountInfoResponseType UpdateAccountInfo(UpdateAccountInfoRequestType myRequest)


UpdateAccountInfoRequestType




firstname String Required

lastName String Required

phone String Required

email String Required

address1 String Optional

address2 String Optional

company String Optional

city String Optional

state String Optional

zip String Optional

Newpin Numeric String Optional

TimeZoneOffset Numeric String Number of hours offset from CST Optional

ObservesDST Numeric String 1-Yes 0-No Optional


UpdateAccountInfoResponseType





Return/Error Codes:


-1 Unexpected Error







184 Required parameter 'firstName' is missing

173 Required parameter 'lastName' is missing

182 Required parameter 'phone' is missing

183 Required parameter 'email' is missing



104 | P a g e



Function: UpdateCreditCard

Updates Credit Card information if account has billing issues, will charge account to get back into good status.

This function accepts 1 parameter, the request, and returns a response. Function Call: UpdateCreditCardResponseType UpdateCreditCard(UpdateCreditCardRequestType myRequest)


UpdateCreditCardRequestType




Firstname String Firstname of account holder Required

lastName String Lastname of the account holder Required

address1 String Postal Address Required

address2 String Additional address info if required Optional

city String City name Required

state String 2 digit State abbreviation Required

zip String Zipcode Required

cardType* Numeric String See Function: GetAvailableCreditCardTypes Required

cardNumber Numeric String Credit card number to be processed Required

expYear Numeric String 4 digit year Required

expMonth Numeric String 2 digit month Required

CVN Numeric String Card Verification Number Required

* Visa=0,Mastercard=1,Discover=2,AmericanExpress=3


UpdateCreditCardResponseType





Return/Error Codes:


-1 Unexpected Error






184 Required parameter 'firstName' is missing

173 Required parameter 'lastName' is missing

174 Required parameter 'address1' is missing

175 Required parameter 'city' is missing

176 Required parameter 'state' is missing or invalid

177 Required parameter 'zip' is missing or invalid



105 | P a g e



178 Required parameter 'cardNumber' is missing or invalid

179 Required parameter 'expYear' is missing or invalid

180 Required parameter 'expMonth' is missing or invalid

181 Required parameter 'CVN' is missing or invalid



106 | P a g e



Function: UpdatePersonID

Updates a personID (personID can be a member of multiple lists)

This function accepts 1 parameter, the request, and returns a response. Function Call: UpdatePersonIDResponseType UpdatePersonID(UpdatePersonIDRequestType myRequest)


UpdatePersonIDRequestType




PersonRecords array

of PersonDetaildata[] Array Person records to be updated Required

PersonDetailData Type:

Parameter Data Type Comments Required?

PersonID Numeric String Required

PrimaryPhone Numeric String Required

Firstname String Optional


Notes String Optional

SecondaryPhone Numeric String Optional

TertiaryPhone Numeric String Optional


UpdatePersonIDResponseType





updateFailures array

of failedUpdates[] Array Results of the update(s)

failedUpdates Type:


personID Numeric String

reason String

Return/Error Codes:


-1 Unexpected Error







107 | P a g e



Function: UpdateSMSInboxStatus

Updates the status of items in the SMSInbox

This function accepts 1 parameter, the request, and returns a response. Function Call: UpdateSMSInboxStatusResponseType UpdateSMSInboxStatus(UpdateSMSInboxStatusRequestType myRequest)


UpdateSMSInboxStatusRequestType




inboxIDs array of

UpdateSMSInboxStatusDetailData[] Array Person records to be updated Required

UpdateSMSInboxStatusDetailData Type:

Parameter Data Type Comments Required?

inboxID Numeric String Required

newStatus Numeric String

Optional

Default=1-mark as read

2-mark as deleted


UpdateSMSInboxStatusResponseType





code

UpdateSMSInboxStatusupdateFailures

array of failedUpdates[] Array Results of the update(s)

UpdateFailures Type:


inboxID Numeric String

reason String

Return/Error Codes:


-1 Unexpected Error







108 | P a g e



Function: WB_CreateAccount RESTRICTED USE

Creates a new WhiteBox customer account

This function accepts 1 parameter, the request, and returns a response. Function Call: WB_CreateAccountResponseType WB_CreateAccount(WB_CreateAccountRequestType myRequest)


WB_CreateAccountRequestType

Parameter Data Type Description / Values Required? Username Numeric String WhiteBox Customer Account credentials Required

Pin Numeric String WhiteBox Customer Pin Required

FirstName String Customer First name Required

LastName String Customer Last name Required

PhoneNumber Numeric String Preferred 10 digit PhoneNumber (NPA)NXX-XXXX

Used as customer username ( >=5 digits <=15 ) Required

EmailAddress String Assists in support calls Recommended

ObservesDST String (1=Default) 1-Yes, 0-Does not observe Required

TimeZoneOffset String TimeZone offset from CST (default=0) Required

transactionTime String The time of the transaction Required

SecurityHash String

Encrypted contents of previous fields separated

by the "|" character. Contact support to have

your encryption keys issued.

Required

ChargeProvider String

0 or Blank = Apple Store

1 - Android/Google

3 - CEA Credit Card Processing

Recommended

If you need to display a selector for customer input, use the following and return the corresponding value for TimeZoneOffset:

Hawaii -4 Alaska -3

Pacific Time (US & Canada) -2 Arizona -1 Mountain Time (US & Canada) -1

Central Time (US & Canada) 0 Eastern Time (US & Canada) 1

Atlantic Time 2


WB_CreateAccountResponseType





AssignedUsername String Newly created username

AssignedPin String Newly created pin

SMSJoinKey String Value for people to opt in to recieve texts.. send to 292929

Return/Error Codes:


-1 Unexpected Error



109 | P a g e











110 | P a g e



Function: WB_FundAccount RESTRICTED USE

Adds funds to a WhiteBox customer account

This function accepts 1 parameter, the request, and returns a response. Function Call: WB_FundAccountResponseType WB_FundAccount(WB_FundAccountRequestType myRequest)


WB_FundAccountRequestType



UsernameToCredit String Username of the account to add funds too Required

Memo String Used for tracking/reference Reccomended

NumberOfCredits Numeric String Number of credits to add to account Required

Base64TransactionReceipt String Transaction Receipt for verification Required

transactionTime String Date+Time the transaction occurred Required

SecurityHash String

Encrypted contents of previous fields

Separated by the "|" character. Contact

support to have your encryption keys issued.

Required


WB_FundAccountResponseType





usernameToCredit String For asynchronous calls to identify result of particular

transaction

Return/Error Codes:


-1 Unexpected Error







TBD TBD

TBD TBD



111 | P a g e



Function: WBCreateAccount RESTRICTED USE / DEPRECATED

Creates a new WhiteBox customer account

This function accepts 1 parameter, the request, and returns a response. Function Call: WBCreateAccountResponseType WBCreateAccount(WBCreateAccountRequestType myRequest)


WBCreateAccountRequestType



UDID String Unique Device ID or Customer Identifier Required

FirstName String Customer First name Required

LastName String Customer Last name Required

PhoneNumber Numeric String Preferred 10 digit PhoneNumber (NPA)NXX-XXXX

Used as customer username ( >=5 digits <=15 ) Required

PinCode Numeric String 5 – 10 digit numeric pincode Required

TimeZoneOffset String TimeZone offset from CST (default=0) Required

ObservesDST String (1=Default) 1-Yes, 0-Does not observe Required

City String Assists in support calls Optional

State String Assists in support calls Optional

Zipcode String Assists in support calls Optional

EmailAddress String Assists in support calls Optional

CallerID Numeric String Depends on Account settings whether this is used Optional

If you need to display a selector for customer input, use the following and return the corresponding value for TimeZoneOffset:

Hawaii -4 Alaska -3

Pacific Time (US & Canada) -2 Arizona -1 Mountain Time (US & Canada) -1

Central Time (US & Canada) 0 Eastern Time (US & Canada) 1

Atlantic Time 2


WBCreateAccountResponseType





Return/Error Codes:


-1 Unexpected Error








112 | P a g e




TBD TBD

TBD TBD



113 | P a g e



Function: WBFundAccount RESTRICTED USE / DEPRECATED

Adds funds to a WhiteBox customer account

This function accepts 1 parameter, the request, and returns a response. Function Call: WBFundAccountResponseType WBFundAccount(WBFundAccountRequestType myRequest)


WBFundAccountRequestType



UDID String UDID of Mobile Device Required

NumberOfCredits Numeric String Number of credits to add to account Required

Memo String Description of transaction or reference-number Optional


WBFundAccountResponseType





Return/Error Codes:


-1 Unexpected Error







TBD TBD

TBD TBD



114 | P a g e



Function: WBPreVerifyAccount RESTRICTED USE / DEPRECATED

Verify that UDID and selected Username do not already exist

This function accepts 1 parameter, the request, and returns a response. Function Call: WBPreVerifyAccountResponseType WBPreVerifyAccount(WBPreVerifyAccountRequestType myRequest)


WBPreVerifyAccountRequestType




selectedUsername String Username to verify is available Required


WBPreVerifyAccountResponseType





UDIDExists String 0-No UDID does not exist, 1-Yes UDID already exists

selectedUsernameExists String 0-No selectedUsername does not exist, 1-Yes already exists

Return/Error Codes:


-1 Unexpected Error







TBD TBD

TBD TBD



115 | P a g e



Function: WBUDIDLookup RESTRICTED USE / DEPRECATED

Returns account information for specified UDID

This function accepts 1 parameter, the request, and returns a response. Function Call: WBUDIDLookupResponseType WBUDIDLookup(WBUDIDLookupRequestType myRequest)


WBUDIDLookupRequestType





WBUDIDLookupResponseType





UDID String The UDID being queried

firstName String First Name

lastName String Last Name

Email String Email Address

Username Numeric String Username associated with this UDID

TimeZoneOffset Numeric String Hours offset from CST

ObservesDST String 0-False 1-True

phoneNumber String The accounts phoneNumber

Return/Error Codes:


-1 Unexpected Error







TBD TBD

TBD TBD



116 | P a g e



Perl Example

ExtCreateBroadcast.pl

#!/usr/bin/perl -w # SOAP client for CEA web service

use strict; use SOAP::Lite;

# To turn on SOAP debugging use this # ================================== # use SOAP::Lite +trace => 'all'; # ================================== # # You will need to put in your own values below # # --------------------------------------- # Enter your username below # --------------------------------------- my $username = '9725551212'; # --------------------------------------- # Enter your pin below # --------------------------------------- my $pin = '1212'; # --------------------------------------- # 1 = Announcement # 2 = Survey # 3 = SMS # --------------------------------------- my $broadcastType = '1'; # --------------------------------------- # 1=SavedList; # 2=CSV; # 3=Comma Delimited String of Phone Numbers # --------------------------------------- my $phoneNumberSource = '3'; # --------------------------------------- # Your descriptive broadcast name # --------------------------------------- my $broadcastName = 'My API Test'; # --------------------------------------- # MessageID to use for broadcast # leave blank to receive 8XX number # and message recording ID # or specify TTSText to use our # Text to Speech Engine # --------------------------------------- my $messageID = ''; # --------------------------------------- # caller id to use, if left blank # will use default from your account # --------------------------------------- my $callerID = '9725551212'; # --------------------------------------- # PhoneNumberSource = 3, comma delimited # list of numbers to call # --------------------------------------- my $commaDelimitedPhoneNumbers = '9725551313, 9725552323';

my $PROXY = 'http://staging-API.call-em-all.com/webservices/ceaapi_v2.asmx';

# For Production use this value for $PROXY # ========================================================================= # my $PROXY = 'http://API.call-em-all.com/webservices/ceaapi_v2.asmx'; # =========================================================================





117 | P a g e



my $soap = SOAP::Lite -> uri('http://call-em-all.com') -> on_action( sub { return '"http://call-em-all.com/ExtCreateBroadcast"' } ) -> proxy($PROXY);

my $method = SOAP::Data->name('ExtCreateBroadcast') ->attr({xmlns => 'http://call-em-all.com/'});

my $query = SOAP::Data->name(myRequest => \SOAP::Data->value( SOAP::Data->name(username => $username), SOAP::Data->name(pin => $pin), SOAP::Data->name(broadcastType => $broadcastType), SOAP::Data->name(phoneNumberSource => $phoneNumberSource), SOAP::Data->name(broadcastName => $broadcastName), SOAP::Data->name(ListID => ''), SOAP::Data->name(phoneNumberCSV => ''), SOAP::Data->name(messageID => $messageID), SOAP::Data->name(messageIDVM => ''), SOAP::Data->name(launchDateTime => ''), SOAP::Data->name(checkCallingWindow => '0'), SOAP::Data->name(callerID => $callerID), SOAP::Data->name(commaDelimitedPhoneNumbers => $commaDelimitedPhoneNumbers) ));

my $result = $soap->call($method => $query);

unless ($result->fault) {

my @crecords = $result->valueof('//ExtCreateBroadcastResponse/ExtCreateBroadcastResult');

foreach my $pcval (@crecords) {

print "\n\n\n"; print "Results of Broadcast Creation\n"; print "=====================================================\n"; if(defined $pcval->{'errorCode'})

{ print "ErrorCode = ".$pcval->{'errorCode'}."\n"; } if(defined $pcval->{'errorMessage'})

{ print "ErrorMessage = ".$pcval->{'errorMessage'}."\n"; } if(defined $pcval->{'broadcastID'})

{ print "BroadcastID = ".$pcval->{'broadcastID'}."\n"; } if(defined $pcval->{'messageRecordingID'})

{ print "MsgRecordingID = ".$pcval->{'messageRecordingID'}."\n"; } if(defined $pcval->{'tollFreeNumber'})

{ print "TollFreeNumber = ".$pcval->{'tollFreeNumber'}."\n"; } if(defined $pcval->{'goodRecordCountOnFile'})

{ print "GoodRecCount = ".$pcval->{'goodRecordCountOnFile'}."\n"; } } } else { print join ', ', $result->faultcode, $result->faultstring, $result->faultdetail; } sub scrub { my $arg = shift; if(! defined $$arg || $$arg eq '' || $$arg eq '(null)') { $$arg = undef; } }

http://call-em-all.com/

http://call-em-all.com/ExtCreateBroadcast




118 | P a g e



PHP Example

ExtCreateBroadcast.php

// ===================== // account information // ===================== $username = "999111999"; $pin = "9991";

// ===================== // 1 = Announcement // 2 = Survey // 3 = SMS // ===================== $broadcast_type = "1";

// ================================= // 1 = listID // 2 = CSV Binary attachment // 3 = CommaDelimited Phonenumbers // ================================= $phone_number_source = "3";

// ===================== // Name of the broadcast // ===================== $broadcast_name = "SAMPLE API Broadcast with TTS";

// ======================================== // leave blank to use default from account // ======================================== $caller_id = "9725551212";

// ============================================================================================== // Phonenumbers to call or text (for text/SMS people have to Opt-In to receive) // // Extended usage: phonenumber|firstname|lastname|notes|secondaryPhone|tertiaryPhone> // // ex "9725551212|Grandma|Moses|Some notes here|9725552300,9725552300|test|number,9725554536" // ============================================================================================== $PhoneNumbers = "9725551313, 9725551212, 9305551212";

// =========================================== // Use Text to Speech to generate the message // =========================================== $TTSText = "This is a test of creating a broadcast with text to speech.";

$proxy = "http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?WSDL";

$client = new SoapClient($proxy, array("trace" => true));

$request = array ( "username" => $username, "pin" => $pin, "broadcastType" => $broadcast_type, "phoneNumberSource" => $phone_number_source, "broadcastName" => $broadcast_name, "phoneNumberCSV" => "", "launchDateTime" => "", "checkCallingWindow" => "0", "callerID" => $caller_id, "commaDelimitedPhoneNumbers" => $PhoneNumbers, "TTSText" => $TTSText, );

$response = $client->ExtCreateBroadcast(array("myRequest" => $request));

http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?WSDL



119 | P a g e



// ===================== // var_dump($response); // =====================

print "errorCode :" . $response->ExtCreateBroadcastResult->errorCode . "\n"; print "errorMessage :" . $response->ExtCreateBroadcastResult->errorMessage . "\n"; print "broadcastID :" . $response->ExtCreateBroadcastResult->broadcastID . "\n"; print "messageRecordingID :" . $response->ExtCreateBroadcastResult->messageRecordingID . "\n"; print "tollFreeNumber :" . $response->ExtCreateBroadcastResult->tollFreeNumber . "\n"; print "goodRecordCountOnFile :" . $response->ExtCreateBroadcastResult->goodRecordCountOnFile . "\n"; print "badRecordCountonFile :" . $response->ExtCreateBroadcastResult->badRecordCountOnFile . "\n"; print "duplicateRecordCount :" . $response->ExtCreateBroadcastResult->duplicateRecrodCountOnFile . "\n"; print "totalRecordCount :" . $response->ExtCreateBroadcastResult->totalRecordCountOnFile . "\n";

if (!IsNullOrEmptyString($response->ExtCreateBroadcastResult->fileUploadErrors->ExtFileUploadError)) { foreach ($response->ExtCreateBroadcastResult->fileUploadErrors->ExtFileUploadError as $detail) { print "===================================== \n"; print "Line Number :" . $detail->lineNumber . "\n"; print "errorCode :" . $detail->errorCode . "\n"; print "errorMessage :" . $detail->errorMessage . "\n"; } }

function IsNullOrEmptyString($question) { return (!isset($question) || trim($question)===''); }



120 | P a g e



CheckAccount.php

// ===================== // account information // ===================== $username = "999111999"; $pin = "9991";

$proxy = "http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?WSDL"; $client = new SoapClient($proxy, array("trace" => true)); $request = array ( "username" => $username, "pin" => $pin, );

$response = $client->CheckAccount(array("myRequest" => $request)); // ===================== // var_dump($response); // =====================

print "errorCode :" . $response->CheckAccountResult->errorCode . "\n"; print "errorMessage :" . $response->CheckAccountResult->errorMessage . "\n"; if ( $response->CheckAccountResult->errorCode === 0) { print "accountStatus :" . $response->CheckAccountResult->accountStatus . "\n"; print "StatusDescription :" . $response->CheckAccountResult->accountStatusDescription . "\n"; print "CallBalance :" . $response->CheckAccountResult->CallBalance . "\n"; print "PendingCallBalance :" . $response->CheckAccountResult->PendingCallBalance . "\n"; print "AvailableCallUnits :" . $response->CheckAccountResult->AvailableCallUnits . "\n"; } function IsNullOrEmptyString($question) { return (!isset($question) || trim($question)===''); }

Python Examples

CheckAccount.py

#!/usr/bin/python

from suds.client import Client

url = 'http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?wsdl'

client = Client(url)

request = client.factory.create('CheckAccountRequestType')

request.username = '999111999'

request.pin = '9991'

response = client.service.CheckAccount(request)

print "ErrorCode :", response.errorCode

print "ErrorMessage :", response.errorMessage

http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?WSDL

http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?wsdl



121 | P a g e



if response.errorCode == 0:

print "AccountStatus :", response.accountStatus

print "Status Descr. :", response.accountStatusDescription

print "Call Balance :", response.CallBalance

print "Pending Balance :", response.PendingCallBalance

print "Available Bal :", response.AvailableCallUnits



122 | P a g e



ExtCreateBroadcast.py

(with Proxy)

#!/usr/bin/python

# The suds SOAP client is not included in the default Python

# distribution and must be installed manually either by manual

# download or easy_install.


url = 'http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx?WSDL'

# If access to CEA is via proxy define the following and

# use as an option in the Client call

proxyOpts = dict()

proxyOpts['http'] = 'http://proxy.domain.com:3128'

client = Client(url, proxy=proxyOpts)

# Create a factory based on the WSDL

request = client.factory.create('ExtCreateBroadcastRequestType')

# Setup the factory based on the WSDL specs

request.username = 99919991

request.pin = 9991

request.broadcastType = 1

request.phoneNumberSource = 3

request.broadcastName = "Sample Create broadcast"

request.messageID = 128342 # -- Refers to an existing broadcast

request.launchDateTime = "6/1/2011 05:00 PM"

request.commaDelimitedPhoneNumbers = "9725551212,9725551313"

result = client.service.ExtCreateBroadcast(request)

if result.errorCode > 0:

print result.errorMessage

else:

print "Broadcast Created Successfully"



123 | P a g e



CheckAccount.py

(with Proxy)

#!/usr/bin/python








proxyOpts = dict()




request = client.factory.create('CheckAccountRequestType')



request.pin = 9991

result = client.service.CheckAccount(request)



else:

print "Status: %s" % result.accountStatusDescription

print "Balance: %d" % result.CallBalance

print "Pending: %d" % result.PendingCallBalance

print "Available: %d" % result.AvailableCallUnits



124 | P a g e



GetbroadcastResult.py

(with Proxy)

#!/usr/bin/python








proxyOpts = dict()




request = client.factory.create('GetBroadcastResultRequestType')



request.pin = 9991

request.broadcastID = 12543 # references an existing broadcast

request.getBroadcastDetails = 1

request.callResultFilter = '*'

result = client.service.GetBroadcastResult(request)



else:

for detail in result.broadcastDetails.CallDetail:

pho = detail.phoneNumber

acc = detail.firstName

nam = detail.lastName

att = detail.numberOfAttempts

tim = detail.lastCallTime

res = detail.callResultName

print "%-10s %-10s %-10s %s %-25s - %s" % (pho,acc,nam,att,tim,res)



125 | P a g e



Bash + cURL Example

GetListContents.sh

#!/bin/bash ( cat <<EOF <soap:envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://wwCw.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <getlistcontents xmlns="http://call-em-all.com/"> <myrequest> <username>##U##</username> <pin>##P##</pin> <listid>##L##</listid> </myrequest> </getlistcontents> </soap:body> </soap:envelope> EOF ) > GetListContents.xml ( cat <<EOF <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes"/> <xsl:template match="soapenv:Body"> <xsl:copy-of select="child::node()"/> </xsl:template> </xsl:stylesheet> EOF ) > cleanit.xsl clear echo echo echo -n "Enter your Username : " read username echo echo -n "Enter your pin (will not echo) :" read -s pin echo echo echo -n "Enter the ListID to retrieve :" read listid echo cat GetListContents.xml | sed -e s/##U##/"$username"/g | sed -e s/##P##/"$pin"/g | sed -e s/##L##/"$listid"/g > glc.xml clear curl -H "Content-Type: text/xml; charset=utf-8" \ -H "SOAPAction:http://call-em-all.com/GetListContents" \ [email protected] \ http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx | xsltproc cleanit.xslt -

exit

http://www.w3.org/2001/XMLSchema-instance

http://wwcw.w3.org/2001/XMLSchema

http://schemas.xmlsoap.org/soap/envelope/


http://www.w3.org/1999/XSL/Transform

http://schemas.xmlsoap.org/soap/envelope/

http://call-em-all.com/GetListContents



126 | P a g e



VBA Example

I had to add references to “Microsoft HTML Object Library” and “Microsoft XML, v6.0”

Private Sub TestXMLHTTP()

Dim username As String

Dim pin As String

Dim broadcastType As String

Dim phoneNumberSource As String

Dim broadcastName As String

Dim checkCallingWindow As String

Dim commaDelimitedPhoneNumbers As String

Dim TTSText As String

Rem ===================================

Rem Use your account credentials here

Rem ===================================

username = "999111999"

pin = "9991"

Rem ================================

Rem BroadcastType = Announcement

Rem ================================

broadcastType = "1"

Rem ================================

Rem Source is comma delimited string

Rem ================================

phoneNumberSource = "3"

Rem ================================

Rem The broadcast name

Rem ================================

broadcastName = "Test from Visual Basic"

Rem ================================

Rem Bypass calling window

Rem ================================

checkCallingWindow = "0"

Rem ====================================

Rem The numbers to call comma delimited

Rem ====================================

commaDelimitedPhoneNumbers = "9725551313"

Rem ================================

Rem Use text to speech for the msg

Rem ================================

TTSText = "Hello, This is a text to speech call testing integration with Microsoft Access 2010. Have a nice day."

Rem ===================================

Rem The endpoint (staging/Production)

Rem ===================================

Dim strURL As String

strURL = "http://staging-api.call-em-all.com/webservices/ceaapi_v2.asmx"

Rem For Production use the following

Rem ================================

Rem strURL = "http://api.call-em-all.com/webservices/ceaapi_v2.asmx"

Rem ================================



127 | P a g e



Dim FunctionName As String

FunctionName = "ExtCreateBroadcast"

Dim SoapPost As String

SoapPost = "<?xml version=""1.0"" encoding=""utf-8""?>" _

& "<soap12:Envelope xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""

← xmlns:xsd=""http://www.w3.org/2001/XMLSchema"" xmlns:soap12=""http://www.w3.org/2003/05/soap-envelope"">" _

& "<soap12:Body>" _

& "<" & FunctionName & " xmlns=""http://call-em-all.com/"">" _

& " <myRequest>" _

& " <username>" & username & "</username>" _

& " <pin>" & pin & "</pin>" _

& " <phoneNumberSource>" & phoneNumberSource & "</phoneNumberSource>" _

& " <broadcastName>" & broadcastName & "</broadcastName>" _

& " <broadcastType>" & broadcastType & "</broadcastType>" _

& " <checkCallingWindow>" & checkCallingWindow & "</checkCallingWindow>" _

& " <commaDelimitedPhoneNumbers>" & commaDelimitedPhoneNumbers & "</commaDelimitedPhoneNumbers>" _

& " <TTSText>" & TTSText & "</TTSText>" _

& " </myRequest>" _

& "</" & FunctionName & ">" _

& "</soap12:Body>" _

& "</soap12:Envelope>"

Rem ================================

Rem Debugging use

Rem ================================

Rem MsgBox (SoapPost)

Rem ================================

Dim xmldoc As Object

Set xmldoc = CreateObject("MSXML2.DOMDocument")

xmldoc.async = False

xmldoc.loadXML (SoapPost)

Dim oReq As Object

Set oReq = CreateObject("MSXML2.XMLHTTP")

Dim oDOM As Object

Set oDOM = CreateObject("MSXML2.DOMDocument.3.0")

oDOM.async = "false"

Dim oNodeList As IXMLDOMNodeList

On Error GoTo ErrRoutine

oReq.Open "POST", strURL, False

oReq.setRequestHeader "Host", "api.call-em-all.com"

oReq.setRequestHeader "Content-Type", "application/soap+xml; charset=""utf-8"""

oReq.setRequestHeader "Content-Length", Len(SoapPost)

oReq.send xmldoc.XML

Rem ================================

Rem Debugging use

Rem ================================

Rem MsgBox (xmldoc.XML)

Rem ================================

oDOM.loadXML (oReq.responseText)

Rem ================================

Rem Debugging use

Rem ================================

Rem MsgBox (oReq.responseText)

Rem ================================

Rem ================================

Rem Destroy the request object

Rem ================================

Set oReq = Nothing

Dim errorCode As String

Dim errorMessage As String



128 | P a g e



Rem ================================

Rem Get the result codes

Rem ================================

Set oNodeList = oDOM.getElementsByTagName(FunctionName & "Result/errorCode")

If oNodeList.length = 0 Then

MsgBox ("FAILURE Proper response not returned")

GoTo EndRoutine

Else

errorCode = oNodeList.Item(0).Text

End If

Set oNodeList = oDOM.getElementsByTagName(FunctionName & "Result/errorMessage")

errorMessage = oNodeList.Item(0).Text

MsgBox ("ErrorCode: " & errorCode & vbCrLf & "ErrorMessage: " & errorMessage)

Rem ================================

Rem Use the XML Dom to get any other

Rem data passed back

Rem ================================

Rem ======================

Rem To be completed soon

Rem ======================

EndRoutine:

Exit Sub

ErrRoutine:

MsgBox Err.Number & " - " & Err.Description, _

vbOKOnly Or vbCritical, _

"TestXMLHTTP"

GoTo EndRoutine

End Sub



129 | P a g e



C++ Example

In my searches for a toolkit that allows easy access to SOAP from C++ I found gSOAP, it is a very active project that lives at :

http://gsoap2.sourceforge.net/ This is not an instruction manual for gSOAP, just the steps that I followed to get a working program to consume the Call-Em-All API. If you have questions and have read the docs, send email to [email protected] and we might be able to be of assistance. Installation Steps I followed: I install all custom software in /usr/local/src so in the following examples I assume that as the starting directory for each of the following steps.

1) Install Pre-requsites (cURL)

(install from an account that has appropriate system priviledges)

wget http://curl.haxx.se/download/curl-7.21.3.tar.gz

gunzip curl-7.21.3.tar.gz

tar -xvvf curl-7.21.3.tar

cd curl-7.21.3

./configure --prefix=/usr

make

make install

2) Install gSOAP (install from an account that has appropriate system priviledges)

wget http://sourceforge.net/projects/gsoap2/files/gSOAP/gsoap_2.8.1.zip/download

unzip gsoap_2.8.1.zip

cd gsoap-2.8/

./configure --prefix=/usr

make

make install

http://gsoap2.sourceforge.net/


http://curl.haxx.se/download/curl-7.21.3.tar.gz



130 | P a g e



3) Pulling the Definitions from the webservice mkdir /usr/local/src/CEAAPI

cd /usr/local/src/CEAAPI

cp /usr/local/src/gsoap-2.8/gsoap/typemap.dat .

(I had issues with using std::string so I uncommented the following line in the typemap.dat to use char* strings when the definition gets created)

<<approx line ~219>>

# To use regular char* strings instead of std::string, use:

xsd__string = | char* | char*

wsdl2h -o CEAAPI.h http://staging-api.call-em-all.com/webservices/CEAAPI_v2.asmx?WSDL

soapcpp2 -i CEAAPI.h -I/usr/share/gsoap/import/

The above line creates all of the sources to be included in your application, now it is just C++ programming.

4) A Sample Program

#include "soapH.h" // include header files

#include "soapCEAAPI_USCOREv2Soap12Proxy.h" // get proxy

#include "CEAAPI_USCOREv2Soap12.nsmap" // get namespace bindings

using namespace std;

int main()

{

CEAAPI_USCOREv2Soap12Proxy q;

q.soap_endpoint = "http://staging-api.call-em-all.com/webservices/CEAAPI_v2.asmx";

// for production use once approved

// q.soap_endpoint = "http://api.call-em-all.com/webservices/CEAAPI_v2.asmx";

char *username = "99919991";

char *pin = "9991";

char *broadcastType = "1";

char *phoneNumberSource = "3";

char *broadcastName = "C++ Example";

char *callerID = "9725551212";

char *phoneNumbers = "9725551313";

char *TTSText = "This is an example of launching a text to speech broadcast";

_ns1__ExtCreateBroadcast *Request = new _ns1__ExtCreateBroadcast;

Request->myRequest = new ns1__ExtCreateBroadcastRequestType;

_ns1__ExtCreateBroadcastResponse *Response = new _ns1__ExtCreateBroadcastResponse;

Response->ExtCreateBroadcastResult = new ns1__ExtCreateBroadcastResponseType;

Request->myRequest->username = username;

Request->myRequest->pin = pin;

Request->myRequest->broadcastType = broadcastType;

Request->myRequest->phoneNumberSource = phoneNumberSource;

Request->myRequest->broadcastName = broadcastName;

Request->myRequest->callerID = callerID;

Request->myRequest->commaDelimitedPhoneNumbers = phoneNumbers;

Request->myRequest->TTSText = TTSText;



131 | P a g e



if (q.ExtCreateBroadcast(Request, Response) == SOAP_OK)

{

printf("ErrorCode : %d \n",Response->ExtCreateBroadcastResult->errorCode);

printf("ErrorMessage : %s \n",Response->ExtCreateBroadcastResult->errorMessage);

if (Response->ExtCreateBroadcastResult->errorCode == 0)

{

printf("\n\n");

printf("BroadcastID : %s \n",Response->ExtCreateBroadcastResult->broadcastID);

printf("GoodrecordCount : %d \n",Response->ExtCreateBroadcastResult->goodRecordCountOnFile);

printf("BadRecordCount : %d \n",Response->ExtCreateBroadcastResult->badRecordCountOnFile);

}

}

else

{

printf("\n\nSomething went horribly awry!\n\n");

q.soap_stream_fault(std::cerr);

}

return 0;

}

5) Compiling

g++ -o sample sample.cpp soapC.cpp soapCEAAPI_USCOREv2SoapProxy.cpp

soapCEAAPI_USCOREv2Soap12Proxy.cpp -lgsoap++

(above all on one line)

6) Running the App

SRV1092:/usr/local/src/CEAAPI# ./sample

ErrorCode : 0

ErrorMessage : Operation Successful

BroadcastID : 12939

GoodrecordCount : 1

BadRecordCount : 0



132 | P a g e



Visual Studio VB.net & C# Example

In this example I am using VS 2010 Professional with SP1 applied

Open Visual Studio 2010

Older version of Visual Studio would actually have a command/menu “Add Web Reference” But in VS2010 SP1 they have hidden it a few levels down in the menus.

Older Versions of VS If you are using VS2008 or VS2010 without the SP1 then you might have a menu option like the following, if so you can jump over the following few pages where we have to navigate to find the equivalent option.



133 | P a g e



Step 1 Creating the Project

Select File -> New Project From the templates on the left select your Programming language of either VB.Net or Visual C# Now select Windows Forms Application from the project types and give it a name.

Project names : c# Project -- "ConsumeWebService" vb.net Project -- “ConsumeWebService-VB”

In this example, I selected .NET Framework 4, but there is no reason that .Net 2.0 would not work. You can find these projects already completed online at :

C# http://cdn.call-em-all.com/files/ConsumeWebService.zip

VB http://cdn.call-em-all.com/files/ConsumeWebService-vb.zip

http://cdn.call-em-all.com/files/ConsumeWebService.zip

http://cdn.call-em-all.com/files/ConsumeWebService-vb.zip



134 | P a g e



Step 2 Build the Form

Now, Expand out the default FORM1 that has been created for you and add the following TextBoxes:

username pin <--- Set as Password Field

commaDelimitedPhonenumbers smsMessage

Labels: (optional)

‘username’ ‘pin’ ‘commaDelimitedPhonenumbers’ ‘smsMessage’

Button: Button1 - Set the text as ‘Send Message’ Your screen should look something like this…



135 | P a g e



Step 3 Add the Web Reference

If you are using VS2008 or an RTM version of VS2010 you might have a menu item called “Add Web Reference” under your Project Menu. If not, use the following steps to navigate to the “Add Web Reference” page. We now need to add a reference to the SOAP API for Call-Em-All..

Select Project --> Add Service Reference

Ignore this page.. what we need is at the bottom left, select Advanced



136 | P a g e



You will now be presented with another Screen called “Service Reference Settings”

Again ignore this page and look to the bottom left, and select Add Web Service

Now Finally, this page has a few things that you actually need to fill out (and be careful with)



137 | P a g e



The first thing is to fill in the URL for the Call-Em-All API… then click the little green arrow


Your system should think for a second as it queries the API for all the services that it provides.

Here is the GOTCHA you need to look out for.. Visual Studio will “recommend” a Web reference name:

DO *NOT* USE THIS NAME AS YOUR WEB REFERENCE NAME



138 | P a g e



Instead use something like CEAAPI_V2

If you try to use the dotted notation, your project may not be able to resolve the reference, and after playing With it for way too long, the simplest solution was to use a simple name and all the build problems went away. After you click the button to add the reference to your Project. You should see the new Web Reference in your Solution Explorer..

We are now ready to hook up our Form to the Web Reference.



139 | P a g e



In your development environment, select FORM1

Now double-click on the button we created in our first steps to get to the “Code Behind” The following pages show sample code in both VB and C# on how to instantiate the API object and to perform an API call to create and send an SMS message.



140 | P a g e



C#



141 | P a g e



VB.Net

Compile and run your project, fill in your account information, the number to send the SMS message to (the number will have had to have opted in before you can message them) See the section in this document called “How Does SMS work at Call-Em-All” and “HOWTO-SMS” for more information.



142 | P a g e



If everything worked correctly, you should have your message delivered…



143 | P a g e



ErrorCodes and ErrorMessages

Any Non-Zero return is an indication that there is a problem with processing the request.

We have an extensive number of error messages that help us diagnose problems that people may be having

while using the API. The detail and level of the messages continues to grow as we add new features, if you

would like to see the entire list, please visit:

http://www.call-em-all.com/dev/API-Errorcodes.aspx

http://www.call-em-all.com/dev/API-Errorcodes.aspx



144 | P a g e



Extended Descriptions

audioID

An audioID is both the “key” field and “Name” of an Audio message that you have created or

uploaded. Methods that currently save to the audioLibrary : ProvideAudio, CreateTTS

All audioID’s use the following format XXNNNN

ex AA0341

These audioID’s can be used (where specified) in place of a messageID, and have the added advantage

of being stored in a queryable format with several attributes.

You can retrieve your audio Libray contents by using the GetAudioLib method.

public struct GetAudioLibDetailData

{

public string audioID;

public string audioDescription; * upcoming search capability

public string userComment; * upcoming search capability

public Boolean isSalesIntro; <- Currently can search by

public Boolean isAudioTTS; <- Currently can search by

public Int32 audioLength; * upcoming search capability

public DateTime dateAdded; * upcoming search capability

public DateTime dateLastUsed; * upcoming search capability

public Boolean hasSalesIntro; <- Currently can search by

public Boolean favorite; <- Currently can search by

public short messageType; * upcoming search capability

public short Active;

}

broadcastID

A broadcastID is a numeric string that identifies a particular broadcast. These numbers increment as

our system makes calls and are never duplicated. Broadcasts are archived after 90 days. If you need a

broadcast restored for reporting purposes, contact us and we can pull the data back into your account

where it will stay until 2:00am that night, whereupon it *will be* archived again.

broadcastType

The system supports 5 types of broadcasts (currently)

Announcement (type 1) Survey (type 2) SMS/Text Message (type 3) SMS or Voice (type 4)

If a number is opted in to receive SMS/Text messages, they Will get an SMS/Text, all other numbers will get a voice call

SMS and Voice (type 5) All numbers will get a voice call, and SMS opt-ins will additionally get an SMS/Text message



145 | P a g e



An announcement is a call broadcast that delivers information, only one message is recorded or used and the system will deliver it to a live answered call and also do it’s best to deliver to an answering machine. A survey expects a response from the user you can request then to press *0 though *9 and we will Report back which number (0-9) they selected. You record or specify 2 messages for a survey, the first is for when a live answer is detected (the questions are asked) and the second is when we detect an answering machine. You may leave instructions on how to register their response on the voice mail message since they obviously cannot press digits for our sytem when they listen to the recording.

callerID

The phone number to display to the called party.

Note: The local telephone company is responsible for converting the Number to a Name

Also, when you send a call to the phone that actually is the same as the callerID, we replace it with one

of our numbers because a lot of PBX and Cellphones behave differently when they see a call coming

from “themselves”

commaDelimitedPhoneNumbers

This parameter in it’s base form is just like it sounds, a list of phonenumbers each separated by a

comma.

But in order to make things easier for certain customers, this was extended to be able to handle the

submission of extended data. By using the pipe character “|” as a separator you can pass in the

following fields: FirstName, LastName, Notes, SecondaryPhoneNumber, TertiaryPhoneNumber.

This was done because a customer needed to more accurately identify their call results, so they did the

following, passed in PhoneNumber|{customerID}, PhoneNumber|{customerID}

CommaDelimitedPhoneNumbers = “9725551212|a1243, 9725551515|A1267, 9725551212|B3412”

Which when they used the GetBroadcastResult method, they could extract the customerID from the

results, this was important because they may have several accounts at a particular phone number and

they needed to know which account had been called.

public struct CallDetail

{

public string phoneNumber; <- Would have the number called

public string firstName; <- Would contain the CustomerID

public string lastName;

public Int16 numberOfAttempts;

public string lastCallTime;

public Int16 callResult;

public string callResultName;

public string surveyResult;

}



146 | P a g e



listID

A listID is a Numeric string and corresponds to a list that you have created that can contain any

number of contacts. You can retrieve your listID’s by calling GetAvailableLists

launchDateTime

Specifies the date and time to send the broadcast. If left blank/null then the broadcast is scheduled to

go out as soon as it is ready (ie if you are calling in to record audio)

The format for the date and time is : MM/DD/YYYY HH:MM AM/PM

messageID

One of the possibly the most misunderstood parameters. The messageID and messageIDVM were

originally used by providing the broadcastID that had a message you wanted to re-use. Since for

surveys you record 2 messages (one for live answer and one for when we detect an answering

machine etc) and customers wanted to mix and match Live vs Answering machine messages from

different broadcasts we allow you to specify the messageID (broadcastID) and messageIDVM

(broadcastID) from two different broadcasts. When you specify a messageID/IDVM, what the system

does is go to that broadcast and look at the files that it referenced for either the Live answer or the

Voicemail. It then uses the referenced files in the new broadcast.

Functions ExtCreateBroadcast and InsertCustomCall can accept AudioID’s in messageID/IDVM fields.

messageIDVM

See messageID

personID

A person ID is a Numeric string that identifies a contact. A person/contact has the following members:

public struct ListDetailData

{

public string PersonID;

public string PrimaryPhone;

public string FirstName;

public string LastName;

public string Notes;

public string SecondaryPhone;

public string TertiaryPhone;

}

When you use AddNumbersToList you are actually creating PersonIDs you can retrieve these by using GetListContents and update them by using UpdatePersonID and finally you can delete them with DeletePerson



147 | P a g e



phoneNumberCSV

A byte[] array of an uploaded comma delimited file (csv/txt) or a Microsoft® Excel Spreadsheet

In C# you would do something like this to load an Excel file:

byte[] myFinalBuffer;

using (FileStream stream = new FileStream(@”PeopleToCall.xls”, FileMode.Open))

{

myFinalBuffer = new byte[stream.Length];

using (BinaryReader reader = new BinaryReader(stream))

{

reader.Read(myFinalBuffer, 0, (int)stream.Length);

reader.Close();

}

}

myRequest.phoneNumberSource = “2”;

myRequest.phoneNumberCSV = myFinalBuffer;

myResponse = p.CreateBroadcast(myRequest);

phoneNumberSource

For methods that allow you to specify multiple recipient, you need to tell us which method you are

going to use to give us that information

Options are :

Saved List (type 1) CSV/Excel File (type 2) Comma Delimted String (type 3)

If you have an existing list on the system you will then specify it for the listID and select Type 1. If you have a saved file (CSV/TXT or Excel Spreadsheet) you will specify Type 2 and then load the file as a binary array. See the definition for phoneNumberCSV for sample code on how to do this. If you are dynamically building your list, most find it easier to use Type 3 and provide a comma delimited string of numbers. See CommaDelimitedPhoneNumbers for more details on advanced formatting.

pin

Required on every method call. This is the same pin that you would use to access your account on the

website. It is 4-10 Numeric digits. The longer the better.



148 | P a g e



smsMsg

The text to be broadcast to your recipients cellphones. You need to be careful with the length of the

message, the max available for you to use is:

US 160 characters. Canada 120 characters

IMPORTANT NOTE: Your message must be 160 characters or LESS after URLEncoding Special characters can take up to 3 character spaces when they are encoded. Do NOT URLEncode your message, we will check the length on submission and return the appropriate success or an error message if it is too long. Example:

This is a <SPECIAL> Text message! Length = 33 becomes This+is+a+%3CSPECIAL%3E+Text+message! Length = 37

TTSText

The text you wish to have converted to speech and played when the recipient answers the phone. This

field works fine with just text typed in, but you can provide a lot of control over speech, pitch,

pronunciation etc by using SSML (Speech Markup Language) see the chapter on Text-To-Speech

username

Required on every method call. This is the same username that you would use to access your account

on the website. It is 5-10 Numeric digits, we recommend using your primary contact phonenumber.



149 | P a g e



Text to Speech

IMPORTANT: You must use single quotes as show in the examples, failure to do so will cause

your audio to either not generate or get truncated

Available Voices

Male: William David Lawrence Female: Callie Allison

Insert this into your TTSText to use the Callie voice: <voice name=’callie’> Insert this into your TTSText to change back* to the William voice: <voice name=’william’> *Yes, you can alternate voices as if they were having a conversation.

Examples of speaking specific data-types

say-as Example How example is read

Cardinal <say-as type='cardinal'>12345</say-as> Twelve thousand three hundred forty five

number:cardinal <say-as type='number:cardinal'>12345</say-as> Twelve thousand three hundred forty five

telephone <say-as type='telephone'>123</say-as> One two three

letters <say-as type='letters'>hello</say-as> H E L L O

spell <say-as type='spell'>hello</say-as> H E L L O

address <say-as type='address'>WA</say-as> Washington

ordinal <say-as type='ordinal'>1</say-as> first

number:ordinal <say-as type='number:ordinal'>1</say-as> first

date_md <say-as type='date_md'>10.20</say-as> October Twentieth

date_mdy <say-as type='date_mdy'>10.20.1998</say-as> October Twentieth Nineteen ninety eight

date:y <say-as type='date:y'>1998</say-as> Nineteen ninety eight

number_digit <say-as type='number_digit'>123</say-as> One two three

time <say-as type='time'>3:45 pm</say-as> Three Fourty-Five P M

telephone <say-as interpret-as='telephone'

format='1'>9725551212</say-as>

Nine seven two <pause> five five five

<pause> one two one two



150 | P a g e



Special Pronunciations (Phonetic Spelling)

For an example, to say “Call-Em-All” I would use the following

<phoneme ph='k ao1 l eh1 m ao1 l'>call-em-all</phoneme>

US English

t [t]ap - [t] ae1 p wa[t]er - w ao1 [t] er0 ba[t] - b ae1 [t]

p [p]at - [p] ae1 t cam[p]er - k ae1 m [p] er0 sto[p] - s t aa1 [p]

b [b]ook - [b] uh1 k a[b]rupt - ah0 [b] r ah1 p t ri[b] - r ih1 [b]

d [d]one - [d] ah1 n ca[d]et - k ah0 [d] eh1 t ba[d] - b ae1 [d]

k

[c]amera - [k] ae1 m r ah0 li[k]ely - l ay1 [k] l i0 ar[ch]ite[c]t - aa1 r [k] ih0 t eh0 [k] t ja[ck] - jh ae1 [k]

g [g]ood - [g] uh1 d bi[gg]er - b ih1 [g] er0 pe[g] - p eh1 [g]

ch

[ch]art - [ch] aa1 r t [c]ello - [ch] eh1 l ow0 na[t]ure - n ey1 [ch] er0 cat[ch] - k eh1 [ch]

jh

[j]ack - [jh] ae1 k di[g]it - d ih1 [jh] ih0 t sol[d]ier - s ow1 l [jh] er0 fu[dg]e - f ah1 [jh]

f

[f]at - [f] ae1 t tele[ph]one - t eh1 l ih0 [f] ow0 n stu[ff] - s t ah1 [f] lau[gh] - l ae1 [f]

v [v]arious - [v] eh1 r i0 ih0 s ha[v]e - h ae1 [v] o[f] - ah1 [v]

th [th]in - [th] ih1 n



151 | P a g e



ma[tth]ew - m ae1 [th] j uw0 ba[th] - b ae1 [th]

dh [th]en - [dh] eh1 n ba[th]ing - b ey1 [dh] ih0 ng brea[th]e - b r i0 [dh]

s

[s]it - [s] ih1 t [ps]ychology - [s] ay0 k aa1 l ih0 jh i0 mi[c]e - m ay1 [s] ma[ss] - m ae1 s

z

[z]ero - [z] i0 r ow0 [x]ylophone - [z] ay1 l ah0 f ow0 n qui[z] - k w ih1 [z] boy[s] - b oy1 [z]

sh

[sh]ip - sh ih1 p [s]ure - [sh] er1 o[c]ean - ow1 [sh] ih1 n cla[sh] - k l ae1 [sh]

zh vi[s]ion - v ih1 [zh] ah0 n ca[s]ual - k ae1 [zh] uw0 ah0 l mira[g]e - m ih0 r aa1 zh

h [h]ello - [h] eh0 l ow1 loop[h]ole - l uw1 p [h] ow0 l

m [m]an - [m] ae1 n co[mm]on - k aa1 [m] ah0 n ga[m]e - g ey1 [m]

n [n]ew - [n] uw1 ca[nn]on - k ae1 [n] ah0 n ma[n] - m ae1 [n]

ng ba[ng] - b ae1 [ng] sitti[ng] - s ih1 t ih0 [ng]

r [r]eason - [r] i1 z ah0 n ba[rr]el - b eh1 [r] ah0 l ca[r] - k aa1 [r]

l [l]ate - [l] ey1 t me[ll]on - m eh1 [l] ah0 n fu[ll] - f uh1 [l]

j [y]ellow - [j] eh1 l ow1 b[ea]uty - b [j] uw1 t i0 will[i]am - w ih1 l [j] ah0 m

w

[w]ater - [w] ao1 t er0 q[u]een - k [w] i1 n cob[w]eb - k aa1 b [w] eh0 b [wh]ether - [wh] eh1 dh er0

i [ea]r - [i1] r sh[ee]p - sh [i1] p k[ey] - k [i1]

ih [i]mage - [ih1] m [ih0] jh b[i]t - b [ih1] t



152 | P a g e



sh[i]p - sh [ih1] p

eh [e]nd - [eh1] n d g[e]t - g [eh1] t f[ea]ther - f [eh1] dh er0

ae [a]frica - [ae1] f r ih0 k ah0 c[a]t - k [ae1] t b[a]nk - b [ae1] ng k

aa [a]ria - [aa1] r i0 ah1 f[a]ther - f [aa1] dh er0 c[a]lm - k [aa1] l m

er [ear]th - [er1] th b[ir]d - b [er1] d m[er]ge - m [er1] jh

ah [a]bout - [ah0] b aw1 t b[u]t - b [ah1] t m[o]nkey - m [ah1] ng k i0

ao [aw]e - [ao1] b[ou]ght - b [ao1] t d[oo]r - d [ao1] r

uh b[oo]k - b [uh1] k f[u]ll - f [uh1] l c[ou]ld - k [uh1] d

uw

[oo]ps - [uw1] p s m[oo]n - m [uw1] n f[oo]l - f [uw1] l ch[ew] - ch [uw1]

ay [i]vy - [ay1] v i0 pr[i]de - p r [ay1] d b[uy] - b [ay1]

aw [ou]t - [aw1] t h[ou]se - h [aw1] s c[ow] - k [aw1]

oy [oy]ster - [oy1] s t er0 b[oy] - b [oy1]

ow [o]bey - [ow0] b ey1 fl[oa]t - f l [ow1] t m[ow] - m [ow1]

ey [a]te - [ey1] t b[a]con - b [ey1] k ah0 n spr[ay] - s p r [ey1]



153 | P a g e



Inserting Pauses

<break strength='none'/>

<break strength='x-weak'/>

<break strength='weak'/>

<break strength='medium'/>

<break strength='strong'/>

<break strength='x-strong'/>

Prosody - Changing the pitch, range, rate and volume

<prosody>

This tag controls the pitch, range, speaking rate, and volume of the text. All attributes are optional, but if no attribute is given an error results. Here is a description of the optional attributes:

pitch=

This attribute modifies the baseline pitch for the text enclosed within the tag. Accepted values are either:

a number followed by the Hz designation a relative change 'x-low' 'low' 'medium' 'high' 'x-high' 'default'

range=

This attribute modifies the pitch range for the text enclosed within the tag. Accepted values for this attribute are the same as the accepted values for pitch.

rate=

This attribute indicates a change in the speaking rate for contained text, accepted values are:

a relative change a positive number 'x-slow' 'slow' 'medium' 'fast' 'x-fast' 'default'



154 | P a g e



The rate is specified in terms of words-per-minute. If the speaking rate is 50 words per minute, then rate=50. If the setting is rate=+10, the speaking rate will be 10 words per minute faster than your current rate setting. Note: When rate is set to a positive number, the implementation is not compliant with the current W3C prosody rate attribute specification.

Volume=

This attribute modifies the volume for the contained text. The range for values is "0.0" to "100.0" or the relative values of :

'silent' 'x-soft' 'soft' 'medium' 'loud' 'x-loud' 'default'

Examples: <prosody pitch='150Hz'> Modified pitch </prosody>

<prosody pitch='-20Hz'> Modified pitch </prosody>

<prosody pitch='+20Hz'> Modified pitch </prosody>

<prosody pitch='-12st'> Modified pitch </prosody>

<prosody pitch='+12st'> Modified pitch </prosody>

<prosody pitch='x-low'> Modified pitch </prosody>

<prosody range='150Hz'> Modified pitch range</prosody>

<prosody range='-20Hz'> Modified pitch range</prosody>

<prosody range='+20Hz'>Modified pitch range</prosody>

<prosody range='-12st'>Modified pitch range</prosody>

<prosody range='+12st'>Modified pitch range</prosody>

<prosody range='x-high'>Modified pitch range</prosody>

<prosody rate='slow'>Modified speaking rate</prosody>

<prosody rate='+25'>Modified speaking rate</prosody>

<prosody rate='-25'>Modified speaking rate</prosody>

<prosody volume='88.9'>Modified volume</prosody>

<prosody volume='loud'>Modified volume</prosody>

<prosody rate='x-slow'> I talk really slow. </prosody>

<prosody rate='slow'> I talk slow. </prosody>

<prosody rate='medium'> I talk at a medium pace. </prosody>

<prosody rate='fast'> I talk fast. </prosody>

<prosody rate='x-fast'> I talk very fast. </prosody>

<prosody rate='default'> I talk normally. </prosody>



155 | P a g e



Staging Considerations

The staging site behaves identical to the production site in almost every fashion except for the following items:

SMS

When sending messages destined for the staging system, you MUST preface all of your SMS messages

with ‘callem ‘

Example: To join a group on the production system you would text the ‘Keyword’ or ‘join Keyword’ to our shortcode of 292929 For staging your message would need to be ‘callem Keyword’ or ‘callem join Keyword’ The callem at the beginning of the message lets our system know that the message is intended for the staging database, not the production database. See HOWTO-SMS

Voice

The staging system has a limited number of outbound ports for making calls. It also does not check the Database as frequently looking for calls to be made. Calls will go out on a much slower basis than what you will see in the production system. Most obviously the 8XX numbers to access different features are different.

Application Production Staging

Message recording with a messageID 866-623-7244 866-284-4401

Log in with User/Pin Immediate Launch 866-623-7525 866-283-1118

Record Sales Introduction message 866-284-5331 N/A

Opt-Out Line 866-284-6198 N/A

Message recording with a messageID (no branding) 877-565-8460 N/A

Play Last message sent to the Calling Number 877-565-8456 N/A



156 | P a g e



How Does SMS work at Call-Em-All

At Call-Em-All, we are very careful to follow both the letter and spirit of the FTC and FCC guidelines imposed on

our industry. We may seem inflexible on some things, but trust me, it’s better than having your service

completely cut off.

1) To send a text message to a cellphone that cellphone user has to have OPTED IN to receive your

messages.

Why is this? Well the main reason is that for a lot of people, TXT messages are not included in their

phone plans. That means that a message from you may cost THEM up to 25c in some cases. This can

add up and I am sure you do not want to be responsible for someone not being able to afford their cell

phone bill.

2) How do I accomplish this?

Opting in is as simple as sending an SMS/Text message. Our system allows you to set up keywords

which you tie to a particular group/ListID. For example you pick the keyword “MONEY”. In order to

join your group or “OPT IN” to receive messages from you, all a person would have do is Text the word

“MONEY” to Call-Em-All’s shortcode [292929]. Sending this message implies that they want to

receive messages from you. Conversely they can also send STOP MONEY to [292929] and they would

in essense revoke your ability to send them Text messages.

3) What tools are available to manage this?

Call-Em-All provides you with your own custom URL that you can link to. This page will tell people the

steps on how to Join or “OPT IN” to receive your messages.

In this example, the keyword selected is “MYLIFE”. After you have created your keyword you will be

able to use the following URL (with your own keyword of course) on your webpage or print media to

give people instructions on how to OPT IN.

http://www.call-em-all.com/join/MYLIFE

http://www.call-em-all.com/join/MYLIFE



157 | P a g e



Your page will look something like this:

4) How can I use the API to manage this?

Our API currently has the following function: GetSMSOptIns

You call the function, pass in a ListID and it will give you the results of who is currently Subscribed or OPTED IN to that list.

You are able to tie different keywords to different groups (think list or ListID), the easiest is to have multiple sub keywords, in the previous example the keyword we used was “MYLIFE”, this is your BASE keyword, anyone texting into it is added to your “Everyone” listing. If you wanted to break people up into more specific groups for certain messages, you could do the following: On one of your existing lists you would add a sub-keyword. In this example we are going to use the sub-keyword “KIDS”, this is for people who only want to receive messages from me that relate to “KIDS” or Kid-safe conten. They would text “MYLIFE.KIDS” to [292929] and their phone would be opted in to receive messages only broadcast to the “Kids” list.

Another example might be that a Church might have a keyword FUMCPLANO and have different lists for specific notifications, such as:

FUMCPLANO.CHOIR FUMCPLANO.ELDERS FUMCPLANO.MEN FUMCPLANO.TEENS

A person who is both a Teen and a Quoir member could sign up for just the messages they wanted by joing only FUMCPLANO.CHOIR and FUMCPLANO.TEENS



158 | P a g e



HOWTO-SMS

This applies to developers working on the staging system, the following shows the similarities and differences between working in Staging and Production. Differences will be highlighted like this. This assumes you have an account set up on http://staging.call-em-all.com

Enabling Text on an Account

When you first log-in you will see the following on the left side of the screen on your “Home” page

You will see the option “Want to send texts?” Click this Link and you will be taken to a set of steps, where you will need to Select “Create Keyword”

Now select your Keyword. Your keyword is what people will use to OPT-IN to receive TEXT/SMS messages from your account. In this example the company name is ACME Widgets, and most people recognize the name so we are going to take advantage of that and set our keyword to “ACME”. *The keyword is NOT case sensitive.

http://staging.call-em-all.com/



159 | P a g e



There are 2 additional items you can enter:

1) An Authorized Phone Number

This is where you can set up an actual phone to be able to initiate SMS messages to the People who opt in to your Keyword(s) *more on additional keywords later

2) A Custom Auto-Reply Message

This is a message that you can enter that will be sent as an Automatic Response when someone OPTS-IN To receive messages from you, it may be just a welcome greeting or something special like “Show this Text the next time you visit us for a special bonus”

*NOTE: For each Auto-Reply message we send out you are charged 1 credit



160 | P a g e



How to Opt People in

There are several ways to get people to opt in, print it in your Literature, Put it on your website, send out a voice broadcast telling people that they can OPT-IN to receive Text messages from you instead of phone calls or email your client or member base with the instructions. We also now have the API function, SendOptInvitation where you can send out invitations to People to opt-in to receive your messages. 1 invitation per number every 90 days

PRODUCTION OPT IN This is where things are just a little bit different, for a production account people can OPT-IN to receive messages by sending either of the following 2 messages to Short Code 292929 Join ACME -> sent to short code 292929 or ACME -> sent to short code 292929

STAGING OPT IN



161 | P a g e



Presumably, if you are reading this document, you are working in the STAGING system with the API. So how do people OPT-IN to the staging system so you can test your code? The only one difference is that when they OPT-IN (or send replies etc) they need to PREFACE their text with the word “callem “. No quotes please but there does need to be a space after the callem prefix. So their Join/OPT-IN would look like this:

callem Join ACME -> sent to short code 292929 or callem ACME -> sent to short code 292929

Other than this one difference, all functionality between production and staging are the same.



162 | P a g e



The 10,000 foot view

(in Progress…)

Call-Em-All and the Call-Em-All API have many different uses and usage scenarios, I am going to identify some

of these at a high level and then drill into each implementation in more detail in hopes of finding something

close to what our customers may want to develop, therefore providing more of a roadmap or How-To.

1) Emergency Notification

2) Job fills and Surveys

3) Response based or end user initiated messages

call-em-all web service / api

Documents