Group

Create or retrieve a group by name

Retrieves or creates a group by name. If a group with that name does not exist, a new normal group will be created, initially empty. (To create a dynamic group, or to create a group with additional options such as solution_id, use project.createGroup.)

post/v1/projects/{project_id}/groups

Request

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

Example request

{
  "name": "Subscribers"
}

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.