Group

Create a group

Creates a new group.

If the filters parameter is provided, the group will be a dynamic group whose members are determined by the filter conditions. Otherwise, it will be a normal group, initially empty, with the ability to manually add members via contact.addToGroup and remove members via contact.removeFromGroup.

Dynamic group filter conditions can later be updated via the filters property of the Group object; a group cannot be converted between a normal group and a dynamic group after it is created.

post/v1/projects/{project_id}/create_group

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/create_group
  • 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

namestring required

Name of the group (must be unique within the project)

filtersobject

Key-value pairs of conditions that contacts must match to be members of a dynamic group. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a vars key, e.g. {"vars": {"city": "Manila"}}); other supported keys are id, name, phone_number, time_created, time_updated, incoming_message_count, outgoing_message_count, last_incoming_message_time, last_outgoing_message_time, conversation_status, send_blocked, group (ID of a normal group whose members should be included), not_group (ID of a normal group whose members should be excluded), and q (full-text search query matching contacts like the search box in the web app). Each value is either a value to match exactly, or an object with an operator such as ne, prefix, gte, lt, exists, or not_exists as the key (e.g. {"gte": 10}).

allow_sendingboolean

True if messages can be sent to this group, false otherwise.

add_time_variablestring

Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable. If the project does not have a contact field with this variable name, a new date/time field will be created. This is useful as the date_variable of a relative campaign that sends messages relative to when each contact joins the group.

solution_idstring

ID of the solution that this group is part of, if any

varsobject

Custom variables and values to set for this group. 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.

Example request

{
  "name": "Subscribers",
  "add_time_variable": "subscription_time",
  "solution_id": "SO2ad0100821a98bea"
}

Response

Successful response

idstring

ID of the group

namestring

Name of the group

dynamicboolean

Whether this is a dynamic or normal group

filtersobject nullable

Key-value pairs of conditions that contacts must match to be members of a dynamic group. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a vars key, e.g. {"vars": {"city": "Manila"}}); other supported keys are id, name, phone_number, time_created, time_updated, incoming_message_count, outgoing_message_count, last_incoming_message_time, last_outgoing_message_time, conversation_status, send_blocked, group (ID of a normal group whose members should be included), not_group (ID of a normal group whose members should be excluded), and q (full-text search query matching contacts like the search box in the web app). Each value is either a value to match exactly, or an object with an operator such as ne, prefix, gte, lt, exists, or not_exists as the key (e.g. {"gte": 10}). Null if this is a normal group. Filter conditions can only be updated on dynamic groups.

num_membersinteger nullable

Number of contacts in the group (null if the group is dynamic)

time_createdinteger

Time the group was created in Telerivet

allow_sendingboolean

True if messages can be sent to this group, false otherwise.

add_time_variablestring nullable

Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable. If the project does not have a contact field with this variable name, a new date/time field will be created. This is useful as the date_variable of a relative campaign that sends messages relative to when each contact joins the group.

solution_idstring nullable

ID of the solution that this group belongs to, if any

varsobject

Custom variables stored for this group. 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.

urlstring

URL to this group in the Telerivet web app

project_idstring

ID of the project this group belongs to

Example response

{
  "id": "CGb0b7201b222fa609",
  "name": "Subscribers",
  "num_members": 142,
  "time_created": 1390343845,
  "add_time_variable": "subscription_time",
  "solution_id": "SO2ad0100821a98bea",
  "url": "https://telerivet.com/p/asdf/group/CGb0b7201b222fa609",
  "project_id": "PJ2ad0100821a98bea"
}

Changes

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