Task

Create a task

Creates and starts an asynchronous task that is applied to all entities matching a filter (e.g. contacts, messages, or data rows). Tasks are designed to efficiently process a large number of entities. When processing a large number of entities, tasks are much faster than using the API to query and loop over all objects matching a filter.

Several different types of tasks are supported, including applying services to contacts, messages, or data rows; adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV.

When using a task to apply a Custom Actions or Cloud Script API service (apply_service_to_contacts, apply_service_to_rows, or apply_service_to_messages), the task variable will be available within the service. The service can use custom variables on the task object (e.g. task.vars.example), such as to store aggregate statistics for the rows matching the filter.

post/v1/projects/{project_id}/tasks

Request

Base URL: https://api.telerivet.com
URL: https://api.telerivet.com/v1/projects/{project_id}/tasks
Auth: one of:
- HTTP basic
- OAuth 2 (authorization code, authorization URL https://telerivet.com/oauth/authorize, token URL https://api.telerivet.com/oauth/token)

Path parameters

project_idstring required

ID of the Project

Request body

task_typestring required

Type of task to create. Each task_type applies to a certain type of entity (such as a contact, message, or data row).

Tasks for contacts:

update_contact_var
add_group_members
remove_group_members
set_conversation_status
set_send_blocked
apply_service_to_contacts
delete_contacts
export_contacts

Tasks for data rows:

update_row_var
apply_service_to_rows
delete_rows
export_rows

Tasks for messages:

cancel_messages
resend_messages
retry_message_services
apply_service_to_messages
add_label
remove_label
update_message_var
delete_messages
export_messages

task_paramsobject

Parameters applied to all matching rows (specific to task_type).

apply_service_to_contacts, apply_service_to_messages, apply_service_to_rows:

service_id - The ID of the service to apply (string)
variables - Optional object containing up to 25 temporary variable names and their corresponding values to set when invoking the service. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Within Custom Actions, each variable can be used like [[$name]] (with a leading $ character and surrounded by double square brackets). Within a Cloud Script API service or JavaScript action, each variable will be available as a global JavaScript variable like $name (with a leading $ character). (object)

**update_contact_var**, **update_message_var**, **update_row_var**:

variable - The custom variable name (string)
value - The value to set (string, boolean, float, null)

**add_group_members**, **remove_group_members**:

group_id - The ID of the group (string)

**add_label**, **remove_label**:

label_id - The ID of the label (string)

**resend_messages**:

route_id - ID of the new route to use, or null to use the original route (string)

**set_send_blocked**:

send_blocked - true to block sending messages, false to unblock sending messages (boolean)

**set_conversation_status**:

conversation_status - "active", "handled", or "closed" (string)

**export_contacts**, **export_messages**, **export_rows**:

storage_id - ID of a storage provider where the CSV file will be saved. (string)

Currently only AWS S3 is supported as a storage provider. This requires creating a S3 bucket in your own AWS account, as well as an IAM user with access key and secret that has permission to write to that bucket. You can configure your own S3 bucket as a storage provider on the Storage Providers page.

Direct downloads are not supported when exporting data via the API. (string)

filename - Path within the storage backend where the CSV file will be saved
column_ids - IDs of columns to save in the CSV file. If not provided, all default columns will be saved. (array of strings, optional)

**delete_contacts**, **delete_messages**, **delete_rows**, **cancel_messages**, **retry_message_services**: No parameters.

Type of filter defining the rows that the task is applied to.

Each filter_type queries a certain type of entity (such as contacts, messages, or data rows).

In general, the task_type and the filter_type must return the same type of entity; however, tasks applied to contacts (other than export_contacts) can also be applied when the filter returns entities that are associated with a contact, such as messages or data rows. (Note that in this case, it is possible for the task to be applied multiple times to an individual contact if multiple messages or data rows are associated with the same contact.)

filter_paramsobject required

Parameters defining the rows that the task is applied to (specific to filter_type).

query_contacts: The same filter parameters as used by project.queryContacts. If you want to apply the task to all contacts, use the parameters {"all": true}.

contact_ids:

contact_ids - IDs of up to 100 contacts to apply this task to (array of strings)

query_messages: The same filter parameters as used by project.queryMessages. If you want to apply the task to all messages, use the parameters {"all": true}.

message_ids:

message_ids - IDs of up to 100 messages to apply this task to (array of strings)

query_rows: The same filter parameters as used by table.queryRows. If you want to apply the task to all rows in the table, use the parameters {"all": true}.

row_ids:

row_ids - IDs of up to 100 data rows to apply this task to (array of strings)

table_idstring

ID of the data table this task is applied to (if applicable).

Required if filter_type is query_rows or row_ids.

varsobject

Initial custom variables to set for the task.

If the task applies a service, the service can read and write custom variables on the task object (e.g. task.vars.example), such as to store aggregate statistics for the rows matching the filter.

Example request

{
  "task_type": "add_group_members",
  "filter_type": "query_contacts"
}

Response

Successful response

idstring

ID of the task

task_typestring

The task type

task_paramsobject

Parameters applied to all matching rows (specific to task_type). See project.createTask.

filter_typestring

Type of filter defining the rows that the task is applied to

filter_paramsobject

Parameters defining the rows that the task is applied to (specific to filter_type). See project.createTask.

time_createdinteger

Time the task was created in Telerivet

time_activeinteger nullable

Time Telerivet started executing the task

time_completeinteger nullable

Time Telerivet finished executing the task

total_rowsinteger nullable

The total number of rows matching the filter (null if not known)

current_rowinteger nullable

The number of rows that have been processed so far

The current status of the task

error_messagestring nullable

Error message if the task failed

varsobject

Custom variables stored for this task. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

table_idstring

ID of the data table this task is applied to (if applicable)

user_idstring

ID of the Telerivet user who created the task (if applicable)

project_idstring

ID of the project this task belongs to

Example response

{
  "id": "DE1189812e59c5c781",
  "task_type": "add_group_members",
  "filter_type": "query_contacts",
  "time_created": 1390348075,
  "time_active": 1390348076,
  "total_rows": 12000,
  "current_row": 3000,
  "status": "active",
  "user_id": "URba3e403e98f49735",
  "project_id": "PJ2ad0100821a98bea"
}

Changes

No recorded changes to this operation across all 1 revision of this API.