Groups

You can create and manage groups programmatically using the Groups API.

Groups are used to organise contacts for messaging and campaigns. In InstaMessage, groups can be created in three ways:

• Manual groups - contacts are added or removed manually
• Auto static groups - rule-based groups evaluated once at creation
• Auto dynamic groups - rule-based groups that update automatically as contact data changes

Manual groups contain a fixed set of contacts that you manage directly.

You can create a manual group by selecting phone numbers or contacts and adding them to a group.

Manual group behaviour:

• Contacts are only added or removed manually
• Membership does not change automatically
• If you add a phone number that does not exist yet, InstaMessage will automatically create the contact

Use manual groups when you want full control over group membership.

Auto groups are created using rules based on contact data stored on contacts, such as:

• Standard contact fields (e.g. first_name, email)
• custom_fields (contact variables)

Auto groups come in two types: static and dynamic.

Auto static groups evaluate their rules once at creation time.

Behaviour:

• Contacts matching the rules are added when the group is created
• Membership does not change after creation
• Contacts are not added or removed automatically if their data changes later

Use auto static groups when you want to build a group from contact data but keep the membership fixed.

Auto dynamic groups continuously evaluate their rules.

Behaviour:

• Contacts are added or removed automatically as their data changes
• No manual maintenance is required
• Group membership always reflects the current contact data

Use auto dynamic groups for long-term segmentation.

custom_fields are persistent key-value fields stored on the contact record.

• You can create custom_fields via the UI or directly via the API
• If you send a new custom_fields key that does not exist yet, InstaMessage will create it automatically
• Auto group rules (static or dynamic) can reference existing or newly created custom fields

Operator compatibility

Operators available in group rules depend on the field type.

• Text fields support operators like contains, starts_with
• Number fields support operators like greater_than, less_than
• Date fields support operators like before, after
• Boolean fields support operators like is_true, is_false

When referencing custom_fields, operators are validated using the field’s stored type as defined on the contact schema.

All groups are created using the Groups API:

POST https://api.instamessage.co.uk/v1/groups

The group type determines whether the group is manual, auto static, or auto dynamic.

{
  "name": "December promo list",
  "type": "manual",
  "members": [
    "+447111222333",
    "+447444555666",
    "+447777888999"
  ]
}

What happens:

• The group is created with the supplied members
• Any phone numbers that do not already exist as contacts are created automatically
• Membership remains fixed until you manually update the group

{
  "name": "VIP customers (snapshot)",
  "type": "auto_static",
  "rules": [
    {
      "field": "custom_fields.customer_type",
      "operator": "equals",
      "value": "vip"
    }
  ]
}

What happens:

• Contacts matching the rules are added at creation time
• Membership does not change automatically after creation

{
  "name": "Spent over 100",
  "type": "auto_dynamic",
  "rules": [
    {
      "field": "custom_fields.spent",
      "operator": "greater_than",
      "value": 100
    }
  ]
}

This requires custom_fields.spent to be typed as number.

What happens:

• The group is created using rules
• Contacts are added or removed automatically as their data changes

• Text operators: equals, not_equals, contains, not_contains, starts_with, ends_with, is_null, is_not_null
• Number operators: equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal, is_null, is_not_null
• Date operators: on, before, after, on_or_before, on_or_after, is_null, is_not_null
• Boolean operators: is_true, is_false, is_null

• Use manual groups for curated or hand-picked lists
• Use auto static groups for one-off segmentation based on contact data
• Use auto dynamic groups for ongoing segmentation
• Populate custom_fields before creating auto groups
• Prefer stable keys like custom_fields.customer_type over free-text fields
• Avoid using frequently changing fields for auto static groups

• Send messages → Send a Message
• Handle inbound replies → Inbound Messages & Replies
• Track delivery → Delivery Receipts & Message Status