This is an old revision of the document!
This API request is initiated with an POST
to the following URL:
http://synappsbeta.plumvoice.com/api/1/outbound/queue
Minimal example: queues a campaign to occur immediately on the user's customers
table, dialing numbers in the phone
column, using the latest revision of the app identified by MkyepUqu8jA
.
$ curl -u username:password -d app_id=MkyepUqu8jA -d tablekey=username:customers -d dial_col=phone http://synappsbeta.plumvoice.com/api/1/outbound/queue
Intermediary example: Same as previous, except results are saved to the result
column and the campaign starts at a specific time.
$ curl -u username:password -d app_id=MkyepUqu8jA -d tablekey=username:customers -d dial_col=phone -d result_col=result -d start_timestamp=1270163564 http://synappsbeta.plumvoice.com/api/1/outbound/queue
Über example: Same as previous but in addition, the campaign expires after one hour, up to three retry calls are placed every two minutes, only rows with status = 'outstanding balance'
are called, and the name
variable in the application is preset with the value of name
in the row being called.
$ curl -u username:password -d app_id=MkyepUqu8jA -d tablekey=username:customers -d dial_col=phone -d result_col=result -d start_timestamp=1270163564 -d last_secs=3600 -d retry=3 -d retry_interval=120 -d "filters[]=status = 'outstanding balance'" -d "params[]=name" -d "fields[]=name" http://synappsbeta.plumvoice.com/api/1/outbound/queue
Each of these examples returns the following response if the campaign was successfully queued:
{ "result": true }
app_id
(string) - Extract this from the URL of your application when open in the editor, looking for the #a=
parameter. e.g., the app_id
for the following URL is MkyepUqu8jA
. http://synappsbeta.plumvoice.com/app/edit#a=MkyepUqu8jA
tablekey
(string) - Identifies the table to be used for the campaign. This is in the format <tableowner>:<tablename>
. It is case and whitespace sensitive. <tableowner>
is the full username of the owner of the table. Valid table names contain only letters, numbers, and the underscore _ character.dial_col
(string) - The column from which numbers to be dialed will be drawn. Valid column names begin with a letter, and contain only letters, numbers, and the underscore _
character. If no rows in the table contain this field, no calls will be made!rev_id
(string) - To always use the latest revision of your app, omit this parameter or submit the string (latest)
. Otherwise, extract this from the URL of the opened revision, looking for the r=
parameter. e.g., the rev_id
for the following URL is iQl
.http://synappsbeta.plumvoice.com/app/edit#a=MkyepUqu8jA,r=iQl
result_col
(string) - The column where the result of each call will be saved. To not save the result anywhere, omit this parameter. If the field does not exist for a row, it will be created. This will overwrite anything currently in the field!start_timestamp
(int) - The number of seconds since midnight, Jan. 1 1970, GMT marking when calls should begin. Omit this parameter to start the calls immediately.last_secs
(int) - The period of time, in seconds, during which calls can be made. This is measured from the start_timestamp
. When this period is over, no further calls will be placed. Omit this parameter to always allow the campaign to proceed to completion.retry
(int) - The number of times that calls should be retried if there was no answer, a busy signal, operator, or fax machine was encountered, or the call was marked to be retried by the Retry this Call module. Omit this parameter or set to 0 to not retry calls. If specified, must be an integer between 0 and 10.retry_interval
(int) - The period of time, in seconds, to wait before retrying a call. This is measured from the beginning of the last attempt. If you omit this parameter, a default of 300 seconds will be used. If specified, this must be an integer between 60 (1 minute) and 172800 (2 days).aggregator
(one of any
or all
, default all
) - Sets whether all filters or any filters should match for a row to be used for this campaign. See Pre-filtering the campaign table below for more information.params[]
(string) and fields[]
(string) - Each param
is an application variable that will be preset with a corresponding field
from the table. This allows you to automatically make data from the call row available to your application within variables. Omit these parameters to not preset any application variables. The order in which you specify params[]
must match the order in which you specify fields[]
, e.g., the following presets the variable foo
to the field bar
and the variable baz
to the field qux
.$ curl … -d "params[]=foo" -d "fields[]=bar" -d "params[]=baz" -d "fields[]=qux" …
Note that any specified variable must actually exist in the application (e.g., by means of the Reserve Variable module) in order for it to be properly preset.
filters[]
(string) - Each filter
is an expression that will be used to select a subset of rows from the table when the campaign is ready to start. Omit this parameter to not filter the table. Up to 8 filters can be specified. See the next section for more information.
The optional filters[]
and aggregator
parameters can be used to select a subset of rows from your table to be called for your campaign. This evaluation is performed when your campaign is just about to start, so changes to the table between the queueing of the campaign and the start_timestamp
of the campaign will affect the callees selected for your campaign. You may have up to 8 filters.
Each filter[]
is an expression of the following format:
<column> <operator> <quoted_value>
<column>
is the name of a column in the table, and must consist of an initial letter followed by only letters, numbers, and the underscore _
character.
<operator>
is one of the following:
operator | meaning | operator | meaning | |
---|---|---|---|---|
= | equals | <= | less than or equal to | |
!= | does not equal | like | contains | |
> | greater than | starts | starts with | |
>= | greater than or equal to | ends | ends with | |
< | less than |
A few advanced operators use a slightly different expression format.
<column>
between
<lower_quoted_value>
and
<upper_quoted_value>
<column>
is null
<column>
is not null
All values, numeric or non-numeric, must be quoted with either single quotes ''
or double quotes ""
. To include a quote character inside the value being quoted, double the quote character. e.g., isn't
becomes 'isn''t'
when quoted with the '
character.
balance < '0'
birthdate >= '08/25/1988'
name = 'frank'
keyword between 'aardvark' and 'apple'
outbound_result is null
The aggregator
parameter controls how the filters are applied. Set aggregator
to all
to have only rows that match all filters become a part of the campaign; set it to any
to have rows that match any filter become a part of the campaign. If omitted, the default of all
is used.
If the campaign was successfully queued:
{ "result": true }
and if not, an error response is issued.