Plum Fuse

API: Queueing an Outbound Campaign

This API request is initiated with an POST to the following URL:

http://quickfuseapps.com/api/1/outbound/queue

Example usage

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://quickfuseapps.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://quickfuseapps.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://quickfuseapps.com/api/1/outbound/queue

Each of these examples returns the following response if the campaign was successfully queued:

{
  "result": true
}

Parameters

Required

  • 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://quickfuseapps.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!

Optional

  • 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://quickfuseapps.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.

Optional, can appear more than once

  • 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.

Pre-filtering the campaign table

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

Quoting rules

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.

Example filters

  • balance < '0'
  • birthdate >= '08/25/1988'
  • name = 'frank'
  • keyword between 'aardvark' and 'apple'
  • outbound_result is null

Combining filters

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.

Response

If the campaign was successfully queued:

{
  "result": true
}

and if not, an error response is issued.

api/outbound_queue.txt · Last modified: 2010/06/13 23:10 (external edit)