Yemot HaMashiach Campaign API version 6

B.H.

Note: this document is a draft - API is not final and is subject to change in the future.

General information

All API calls should use HTTP POST or HTTP GET. Request arguments should be passed in URL-encoded format. For GET request they should be passed in the query string itself, for POST they should be passed in request’s body.

For POST request, multipart/form-data request format is also supported. It is required to upload files using UploadFile service.

All API calls must be sent to API’s base URL:

https://www.call2all.co.il/ym/api/<WebServiceName>[?p1=v1[&p2=v2...]]

API’s base URL is subject to change. For testing, different URL may be supplied.

In the following examples, the base URL will be omitted.

All API responses except for file downloads (DownloadFile/DownloadCampaignReport) will be encoded in JSON format. General response format is as follows:

{

"yemotAPIVersion": "<API version>",

"responseStatus": "<response status>",

....

}

Common properties (exist in all responses):

1. "yemotAPIVersion": will be set to the current API version (may be used to detect compatibility issues with future versions)

2. "responseStatus": if the requested action completed successfully, will be set to "OK". If the action failed, the value will be "ERROR" and error message will be supplied as "message" property, "FORBIDDEN" means the request was forbidden by the server, "EXCEPTION" means the call caused exception in the server.

Example of API response with error message:

{

"yemotAPIVersion": "1",

"responseStatus": "ERROR",

"message": "Username or password is incorrect",

"messageCode": 1

}

In this example, error message is returned, messageCode is a numeric code that identifies the error condition. If messageCode == null, generic error has occured, textual explanation is available in 'message' property.

For download calls, the downloaded content is sent directly as a response, with appropriate Content-Type header.

Supported API calls

Login

Request parameters:

Parameter	Usage
username	Customer’s user name
password	Customer’s password

Response properties (on successful login):

Property

Meaning

token

NOTE: The created token will expire after 60 minutes if not API call is made with the token.

Logout

log out of the session

Request parameters:

Parameter	Usage
token	Login session token

Response properties: none

GetSession

get basic session data

Request parameters:

Parameter	Usage
token	Login session token

Response properties:

Property	type	Meaning
username	string	Logged in user name
units	double	Units balance
unitsExpireDate	string	Units expire date or null in none

SetPassword

Set user's password

Request parameters:

Parameter	Usage
token	Login session token
password	Customer's current password
newPassword	The new password to set

RunCampaign

Start a campaign based on existing Campaign Template

This call creates a campaign based on one of the customer's templates, then, if the campaign is configured properly and the customer has enough balance, runs the campaign.

On success, campaignId is returned. This value must be used to track the campaign's status and to get the final report data.

On failure (campaign is not configured correctly, customer's balance is not enough), error response is returned.

"phones" parameter is optional and if specified it will be used to substitute the original phone list with another "transient" phone list which is not saved in the original campaign template. Phone numbers must be delimited with ":" like this:

Examples:

; run campaign based on the original template setup "as is"

https://....../RunCampaign?token=XXXXXXX&templateId=123

; run campaign and dial only to 0501234567

https://....../RunCampaign?token=XXXXXXX&templateId=123&phones=0501234567

; run campaign and dial to 0501234567 and 0547654321

https://....../RunCampaign?token=XXXXXXX&templateId=123&phones=0501234567:0547654321

Request parameters:

Parameter	Usage
token	Login session token
templateId	Existing Campaign Template id
phones	Override the original phone list with the given phone list. Phone numbers must be delimited by ":". Any invalid phone numbers are ignored, if the parameter is specified but no valid phone numbers found, error message will be returned.
callerId	Override the callerId from the template with another callerId that is allowed for the customer

Response properties on success:

Property	type	Meaning
templateId	int	template id
campaignId	string	string that should be used to identify the campaign
entriesCount	int	total number of entries in the campaign
pending	int	number of campaign entries that are active and are going to be dialed
blocked	int	number of campaign entries that are blocked
estimatedPrice	double	estimated price for the campaign in customer's units
customerUnits	double	customer's units balance at the time the campaign was started

On failure error response will be returned, possible messages and codes are as follows:

messageCode	message	explanation
100	Template is invalid	templateId value is invalid (template does not exist or does not belong to the logged in customer)
101	Campaign setup is invalid	the campaign is not properly configured (phone list is empty, no valid message, etc)
102	No valid phones	All phones that were supplied with phone parameter are unacceptable
103	Not enough units	customer's units balance is not enough to proceed
104	isKodesh is true	Attempt to run a campaign on Shabbat or Yom-Tov.
105	General error	System error has occured and the campaign can not be started
120	CallerId is not allowed	The requested callerId is not allowed for the customer

GetCampaignStatus

Get the current status of campaign identified by campaignId

Request parameters:

Parameter	Usage
token	Login session token
campaignId	Campaign's id string as returned by RunCampaign request

Response properties on success:

Property	type	Meaning
campaign	object	Campaign's status data (see below)

On failure error response will be returned, possible messages and codes are as follows:

messageCode	message	explanation
106	Campaign not found	campaignId was not found for this user

On success campaign property will contain object that describes campaign's status. This object's properties will be in 1 of 2 formats, depending on the campaign's status. Campaign's status can be distinguished by campaignStatus property of the object. If campaignStatus=="FINISHED" then the object's format will be of a finished campaign, otherwise the format will be of an active campaign.

Active campaign status object properties:

Property	type	Meaning
campaignId	string	Campaign's ID
campaignStatus	enum	one of STOPPED,RUNNING,PAUSED,STOPPING
templateId	int	templateId on which the campaign is based
who	string	Who have started the campaign (IP or phone number)
callerId	string	Outgoing calls caller id
blockedEntries	int	blocked entries count
pendingEntries	int	current pending entries count
activeEntries	int	current active entries count
bridgedEntries	int	current bridged entries count
redialEntries	int	count of entries awaiting redial
doneEntries	int	entries successfully dialed
failedEntries	int	entries that have failed
totalEntries	int	total entries
totalDialed	int	total calls (including redials)
totalSuccessful	int	total successful calls (not failed)
totalBridged	int	total bridged calls
totalFailed	int	total failed calls
totalIncoming	int	total incoming calls during campaign
totalIncomingBridged	int	total incoming bridged calls
maxActiveChannels	int	maximum allowed active calls per campaign
maxBridgedChannels	int	maximum allowed bridged calls per campaign
maxDialAttempts	int	maximum redial attempts
redialWait	double	minimum wait between redial attempts in seconds
redialPolicy	enum	one of: NONE=no redials at all CONGESTIONS=redial calls that did not reach the called party FAILED=also redial unanswered calls
vmDetect	boolean	voicemail detection enabled
playPrivateMsg	boolean	private message mode enabled
runTime	double	total campaign's run time in seconds
currentPrice	double	current price in units
paused	boolean	Is the campaign paused currently?

Finished campaign status object properties:

Property	type	Meaning
campaignId	string	Campaign's ID
campaignStatus	enum	always FINISHED
price	double	Amount of units charged for the campaign
finishedTime	string	When the campaign run was finished, format like this: 2015-04-16 21:01:00
who	string	Who have started the campaign (IP or phone number)

GetActiveCampaigns

Get status for all active campaigns

Request parameters:

Parameter	Usage
token	Login session token

Response properties on success:

Property	type	Meaning
campaigns	array	Array of objects. Each object describes one active campaign. Object's properties are the same as for active campaign data returned by GetCampaignStatus request

CampaignAction

Perform action on a running campaign

This service is used to control a running campaign. It can be used pause, stop the campaign or change it's settings "on the fly".

Request parameters:

Parameter	Usage
token	Login session token
campaignId	Campaign's id string as returned by RunCampaign request
action	The action to perform (see below)
value	The action's argument

Supported actions:

Action value	Meaning
stop	Stop (kill) the campaign.
setPaused	Set campaign's paused state. Value must be 0 for not paused or 1 for paused state. Paused campaign will be in "hold" state (active but not running) for up to 1 hour. Campaigns that remain in paused state for more than 1 hour will be stopped automatically.
setMaxActiveChannels	Set maximum active channels setting on the fly
setMaxBridgedChannels	Set maximum bridged channels setting on the fly

Response properties on success:

Property	type	Meaning
campaign	object	The campaign's status current status after the action. Object's properties are the same as for active campaign data returned by GetCampaignStatus request.
action	string	The action that was executed
value	string	The action's argument

UploadFile

Upload a file to the server

This service must be called using HTTP POST with multipart/form-data encoding. Only single file upload per request is supported. Request parameters may be specified in the query string as in GET request or in request body using multipart/form-data encoding.

Request parameters:

Parameter	Usage
token	Login session token
path	Upload destination path. The path is relative to the customer's root directory and must contain both directory and the file name. See below for file naming conventions used with campaigns.
convertAudio	(optional, default is 0) If convertAudio=1, the uploaded file will be automatically converted to WAV format suitable for the telephony. The source file may be in any of most popular audio formats (MP3, OGG, WMA etc). Note: path parameter must point to the destination file after the conversion (so it must be with .wav extension!)

Response properties on success:

Property	type	Meaning
path	string	The uploaded file path, as passed by path parameter
size	long	The uploaded file size in bytes

If convertAudio=1, then additional properties will be returned in the response:

Property	type	Meaning
convertedSize	long	The converted WAV file size in bytes
duration	double	Audio duration in seconds

On failure error response will be returned, possible messages and codes are as follows:

messageCode	message	explanation
105	System error	General error while handling the upload
107	File upload expected	No uploaded file was found in the request
108	Only single upload per request is supported	More than 1 uploaded file in single request
109	path is required	no path parameter
110	path is invalid	path parameter value is invalid

In order to test HTTP uploads this simple form can be used:

https://www.call2all.co.il/ym/api_upload_test.php

The following path values can be used to upload campaign-related audio files:

${templateId} is the templateId value as used in RunCampaign call

${phone} is the phone number of the called party (phone number that was dialed by the campaign)

path	Description
${templateId}.wav	Main campaign message
${templateId}-MoreInfo.wav	This message is played for bridged calls, after the user pressed 1, before the call is transferred

When the "private message mode" is enabled for campaign (see playPrivateMsg property in GetTemplates / GetCampaignStatus calls), additional files are used to play the private messages:

path	Description
${templateId}-First.wav	This message is played before the private message
PrivateMsg/${phone}.wav	The private message to be played for specific phone
PrivateMsg/Default.wav	The private message to be played if specific message does not exist for the called phone number

In "private message mode", the messages are played in the following order:

1. the "first" message is played (if exists)

2. the private message that corresponds to the dialed phone number is played (or default if no specific file)

3. then, the main campaign message is played as usual

DownloadFile

Downloads a file from the server

Request parameters:

Parameter	Usage
token	Login session token
path	A file to download (relative to the customer's root directory)

Note that this request's response is not JSON! The response will contain the requested file contents. Content-Type header is application/binary.

In case the file does not exist or error has occured, HTTP 404 Not Found response will be generated.

DownloadCampaignReport

Downloads a finished campaign report from the server

Request parameters:

Parameter	Usage
token	Login session token
campaignId	Campaign's id string as returned by RunCampaign request

Note that this request's response is not JSON! The response will contain the requested report file as html. Content-Type header is text/html.

In case the file does not exist or error has occured, HTTP 404 Not Found response will be generated.

GetTemplates

get all campaign templates data

Request parameters:

Parameter	Usage
token	Login session token

Response properties:

Property	type	Meaning
templates	Array of objects	array of objects defining all existing templates (see below)

Template descriptor object:

Property	Type	Meaning
templateId	int	the template's id
description	string	Text description or null if not defined
callerId	string	Outgoing calls caller id
entriesCount	int	Total (active+blocked) entries count
blockedEntriesCount	int	Blocked entries count
incomingPolicy	enum	OPEN\|BLACKLIST\|WHITELIST\|BLOCKED Template's incoming calls poicy (in use for customer's default template only)
customerDefault	boolean	is the template "default" (used for incoming calls)
maxActiveChannels	int	max. active channels the campaign
maxBridgedChannels	int	max. bridged channels the campaign
originateTimeout	double	timeout for dial in seconds
vmDetect	boolean	activate automatic voicemail detector function
maxDialAttempts	int	maximum dial attempts for redials
redialWait	double	minimum time between redial attempts
redialPolicy	enum	NONE\|CONGESTIONS\|FAILED\|EMERGENCY redial policy
yemotContext	enum	SIMPLE\|MESSAGE\|VOICEMAIL\|BRIDGE\|OTHER Campaign's calls context selector
bridgeTo	string	a phone number to dial for brided calls
playPrivateMsg	boolean	private message mode enabled
removeRequest	enum	NONE\|SILENT\|WITH_MESSAGE remove request mode
messageExists	boolean	campaign's message file exists
messageDuration	double	message file duration in seconds
unitsPerMessage	double	estimated cost in units per message
moreinfoExists	boolean	"more info" message exists (played before the call is briged)
moreinfoDuration	double	"more info" message duration in seconds

CreateTemplate

Create new campaign template record

Request parameters:

Parameter	Usage
token	Login session token

Response properties on success:

Property	type	Meaning
templateId	int	Newly created template id. The new template will have the default setup cloned from the customer's default template

DeleteTemplate

Delete customer's template record

Request parameters:

Parameter	Usage
token	Login session token
templateId	Template id to delete. Note that customer's default template can not be deleted.

UpdateTemplate

Change the template's settings

Request parameters:

(Note: token and templateId are required parameters, all other parameters are optional.
Only settings for the supplied parameters will be updated, omitted settings will not be changed)

Parameter	type	Usage
token	string	Login session token
templateId	int	Template id to edit
description	string	Text description for the template
callerId	string	Outgoing caller id
yemotContext	enum (string)	Outgoing calls behavior - one of: SIMPLE: simply play message and hangup MESSAGE: record message and send by email VOICEMAIL: record message and send to customer's VM BRIDGE: bridge the call to bridgeTo number (additional costs will apply to the bridged call)
bridgeTo	string	phone to dial in yemotContext=BRIDGE mode
removeRequest	enum (string)	Remove request mode - one of: NONE: no remove request allowed SILENT: remove request allowed but no message WITH_MESSAGE: standard remove request message will be played after the campaign's message
customerDefault	boolean (1/0)	if 1, set the current template as customer's default
incomingPolicy	enum (string)	Incoming calls policy setup. Only relevant for the default template. One of: OPEN: Anybody can call BLACKLIST: Blocked numbers are forbidden WHITELIST: Only numbers from the dial list are allowed BLOCKED: No incoming calls allowed
maxActiveChannels	int	Maximum active calls in parallel
maxBridgedChannels	int	Mamimum bridged calls in parallel
originateTimeout	double	Time limit for dialing outgoing calls
redialPolicy	enum (string)	Redialing policy. One of: NONE: no redials at all CONGESTIONS: redial only calls that failed locally FAILED: redial all unsuccessful calls
maxDialAttempts	int	Maximum dial attempts for each campaign entry
redialWait	double	Minimum seconds before redial
vmDetect	boolean (1/0)	Enable automatic voicemail detection system
playPrivateMsg	boolean (1/0)	Enable playing customized message based on the called number (the custom messages need to be in PrivateMsg directory)

Response properties on success:

Property	type	Meaning
template	object	the updated template data. The format is the same as the template descriptor in GetTemplates call.

GetTemplateEntries

Get the list of template's entries (phone numbers to dial)

Request parameters:

Parameter	Usage
token	Login session token
templateId	Template id

Response properties on success:

Property	type	Meaning
templateId	int	Template id
entries	array	Array of "entry" objects for all template entries

Entry object format:

Property	type	Meaning
rowid	int	Entry's unique id
phone	string	Phone number
blocked	boolean	Is the entry in "blocked" state?
name	string	Associated name or null if not set
moreinfo	string	Associated additional info string or null if not set

ClearTemplateEntries

Delete all template entries

Request parameters:

Parameter	Usage
token	Login session token
templateId	Template id

UpdateTemplateEntries

Update blocked status or delete template entries

Request parameters:

Parameter	Usage
token	Login session token
templateId	Template id
rowids	rowid values for entries to be updated/deleted, separated by "-" like this: 12345-543321-12346
action	One of: "block": set blocked=true "unblock": set blocked=false "delete": delete

UpdateTemplateEntry

Update or add single template entry

Request parameters:

(Note: all parameters excluding token and templateId are optional.
If rowid is specified, will update the given row, if it is omitted, will add new row

For other optional parameters the value will be left unchanged, or null for new entry if omitted)

Parameter	Usage
token	Login session token
templateId	Template id
rowid	rowid to update. If the parameter is omitted, new entry will be created
phone	Phone number to dial
name	Associated name
moreinfo	Additional info string
blocked	blocked status: 0 = unblocked (default), 1 = blocked

TransferUnits

Transfer units to another customer

Request parameters:

Parameter	Usage
token	Login session token
destination	Destination customer (DID number)
amount	Amount of units to transfer

Response properties on success:

Property	type	Meaning
destination	string	Destination customer
amount	double	Amount transferred
newBalance	double	New balance of the sender

On failure error response will be returned, possible messages and codes are as follows:

messageCode	message	explanation
111	Bad destination	Destination is unacceptable: customer does not exist or is not allowed to receive units from the current customer
112	Bad amount	Amount value is invalid
113	Not enough balance	Customer's balance is not enough to fulfil the transfer

GetTransactions

Get a list of customer's transaction (including finished campaign reports)

This service returns a list of transactions in customer's units account. Transactions that represent charges for the finished campaigns include the campaignId value that can be used to get the campaign status and report.

Note: 'from=X' and 'limit=Y' parameters act like 'limit X,Y' clause in SQL.

Request parameters:

Parameter	default	Usage
token	required	Login session token
from	int	(optional) first transaction to include
limit	int	(optional) maximum number of transactions to include

Response properties:

Property	type	Meaning
transactions	array	Array of objects (see transaction object below)
totalCount	int	Total number of transactions for the customer

Transaction object format:

Property	type	Meaning
id	int	Unique transaction id
transactionTime	string	The time of the transaction (format: yyyy-MM-dd HH:mm:ss)
amount	double	Transaction amount in units
description	string	Transaction's description. See below for special keyword
who	string	Who initiated the transaction. One of: 1) IP address - for web or WS based transactions 2) Phone number (for IVR-based transactions 3) "ADMIN" = administrator or customer service 4) "TRANSFER" = Units transfer (receiver side) 5) "expire" = Units expired
newBalance	double	The new account balance after the transaction
expireDate	string	The new expiration date or null if none set. (format: yyyy-MM-dd)
campaignId	string	If the transaction is a charge for campaign, this will contain the campaignId value suitable for GetCampaignStatus and DownloadCampaignReport services. Otherwise, this will contiain null

Special description keywords that can be used to identify some transaction types:

Description string starts with	Meaning
Start-	A charge for campaign
transfer to	Units transfer (source)
transfer from	Units transfer (destination)
Units expired	Units expiration

UploadPhoneList

Upload text and parse it as a phone list

Request parameters:

Parameter	default	Usage
token	required	Login session token
templateId	required	Template to update
data	required	The phone list file as a string
nameColumns	1	Number of columns for 'name'. All other text columns go to the 'more info'
defaultPrefix	(none)	Default phone number prefix for 7-digit numbers. Allowed values are: 02,03,04,08,09,077,072,073. No default prefix by default.
delimiter	, (comma)	Column delimiter for the file. Any single character is allowed. Use 'TAB' for 'tab' (\t) delimited files
updateType	UPDATE	Enum: UPDATE\|NEW\|REMOVE. Defines the update mode: UPDATE = update existing records and add new NEW = remove all existing records and add new REMOVE = remove records
blocked	0	If 1, will set the uploaded records status to 'blocked'.

If the file parsing fails due to unrecognized format, will return response with message="bad_format".

If the parsing is successful, will return the following response:

Property	type	Meaning
message	string	"ok" - means the upload was processed properly
templateId	int	the template id that was updated
totalParsed	int	total number of records that were accepted
rejectedRecords	Array	Array of object that describe the rejected records (see below)
totalInserted	int	Total number of newly inserted records
totalUpdated	int	Total number of updated records
totalRemoved	int	Total number of removed records

If some records were rejected for some reason, rejectedRecords will contain an array of objects in the following format:

Property	type	Meaning
phone	string	the phone number
name	string	Name column
moreinfo	string	More info column
blocked	bool	blocked status
errorState	enum	DUPLICATE = the number is duplicate INVALID = the number is invalid (not allowed in campaigns)
originalRowNumber	int	The row number where error was detected

ScheduleCampaign

Schedule campaign to be run later

Schedule a campaign, based on templateId to be run on a later time

Request parameters:

Parameter	Usage
token	Login session token
templateId	Existing Campaign Template id
time	Time to schedule the campaign as a string. The time may be in one of the following formats: yyyy-MM-dd-HH:mm:ss yyyy-MM-dd-HH:mm yyyy-MM-dd HH:mm:ss yyyy-MM-dd HH:mm:ss HH:mm

Response properties on success:

Property	type	Meaning
templateId	int	template id
schedTime	string	The scheduled campaign time in format: yyyy-MM-dd HH:mm:ss
schedId	int	Unique scheduled campaign id. This value may be used to delete the scheduled campaign later
entriesCount	int	total number of entries in the campaign
pending	int	number of campaign entries that are active and are going to be dialed
blocked	int	number of campaign entries that are blocked
estimatedPrice	double	estimated price for the campaign in customer's units
customerUnits	double	customer's units balance at the current time

On failure error response will be returned, possible messages and codes are as follows:

messageCode	message	explanation
100	Template is invalid	templateId value is invalid (template does not exist or does not belong to the logged in customer)
101	Campaign setup is invalid	the campaign is not properly configured (phone list is empty, no valid message, etc)
105	General error	System error has occured and the campaign can not be started
110	time is invalid	Unable to parse the value of time parameter or the time is in the past

GetScheduledCampaigns

Get a list of scheduled campaigns

Gets a list of the scheduled campaign records of particular type (status)

Request parameters:

Parameter	Usage
token	Login session token
type	What type of records to return. Possible values (not case sensitive): PENDING: pending (awaiting execution) records SUCCESSFUL: successfully executed scheduled campaigns FAILED: failed scheduled campaigns
order	The records are sorted by the scheduled time. Sorting order: asc (default): ascending order desc: descending order
from	(optional) first record to include
limit	(optional) maximum number of records to include

Response properties on success:

Property	type	Meaning
totalCount	int	Total records count of the specified type
scheduledCampaigns	Array of objects	List of all matching records (see Scheduled campaign object format)

Scheduled campaign object format:

Property	type	Meaning
schedId	int	Record id as returned in schedId property of ScheduleCampaign
templateId	int	The scheduled template id
templateDescription	string	The template description (as in description property of GetTemplates)
ip	string	IP address that ScheduleCampaign was run from
createTime	string	Record creating time in format: yyyy-MM-dd HH:mm:ss
startTime	string	The scheduled campaign time in format: yyyy-MM-dd HH:mm:ss
pending	boolean	Is the record pending execution
error	boolean	Was error encountered on the scheduled campaign execution?
campaignId	string	If the campaign was executed, the property will campaign the campaign id that can be used to get the campaign's status using GetCampaignStatus
errorMsg	string	On error, will contain textual error message explaining why the execution failed

DeleteScheduledCampaign

Delete previously created pending scheduled campaign record

Request parameters:

Parameter	Usage
token	Login session token
schedId	The record's schedId as returned by ScheduleCampaign or GetScheduledCampaigns

Response properties on success:

Property	type	Meaning
message	string	"ok" means the action was executed successfully

On failure error response will be returned, possible messages and codes are as follows:

messageCode	message	explanation
105	invalid schedId	The supplied schedId is not valid
106	schedId is not pending	The supplied schedId is valid, but the scheduled campaign was already executed