Skip to main content

Client Tags

A tag in Sailplay is a named label assigned to a specific client that captures a significant state of the profile or a fact of interaction.

Client tags are at the base of:

  • trigger scenarios,
  • segmentation,
  • automations,
  • analytics,
  • personalized communications.

Types of Tags​

By meaning, tags are divided into two types:

  • Event Tag — reflects an action performed.
    For example: "Confirmed email", "Left request", "Opened email".

  • Segment Tag — reflects the client's membership in a group.
    For example: "VIP status", "Android device", "Age: 21–25".

Tag Classification​

In Sailplay, tags are divided into two categories:

  • System Tags
  • User Tags

⚙️ System Tags​

System tags are built into the platform and assigned automatically.

How they appear​

Assigned during:

  • system events,
  • client profile updates,
  • the presence of certain data (for example, birth date).

Who manages them​

You cannot delete or change a system tag.
In certain cases, removing a tag from a specific client is allowed if provided for by the logic.

What they are used for​

Used as universal attributes:

  • for segmentations,
  • for automations,
  • for trigger scenarios.

Examples of System Tags​

  • Registration in Loyalty Program
    Assigned automatically when a client is created via the method /api/v2/users/add/.

  • Birthday
    Used to launch scenarios on a birthday or at a set time before it.

  • Email Changed
    Assigned when a client's email is changed.
    The previous email is saved in the parameters.

🙋 User Tags​

Tags that the partner creates independently for business tasks.

How they appear​

  • manually in the Sailplay interface,
  • via autosegmentations,
  • via trigger scenarios,
  • via API.

Who manages them​

Fully managed by the partner:

  • creation,
  • renaming,
  • assignment,
  • removal.

What they are used for​

Allow for:

  • implementing business logic,
  • launching complex scenarios,
  • managing personalization.

Tag Types​

Each tag has a type:

🚩 Flag​

  • Can be assigned to a client only once.
  • Repeated assignment is ignored.

🧮 Counter​

  • Can be assigned multiple times.
  • The count is displayed in the client's profile.

Tag Parameters​

Parameters are additional data passed along with the tag.

Parameter Capabilities​

  • Arbitrary structure (key → value);
  • Insertion into message templates;
  • Array support;
  • Display in the client card.

Example of Simple Parameters​

{
  "params": {
    "discount_code": "SALE2025",
    "bonus_points": "150"
  }
}

API Method Map for Clients​

GroupPurposeMethod URL
TagsAssign tags/api/v2/users/tags/add/
Remove tags/api/v2/users/tags/delete/
Get list of tags/api/v2/users/tags/list/
Bulk tag assignment/api/v3/tags/add/bulk
Bulk tag removal/api/v2/users/tags/delete/bulk/
Assign tags without client creation/api/v2/users/tags/assign

Assign Tags​

The method allows adding one or more tags to a user.

Multiple tags: you can pass several tags separated by commas.

Space sensitivity: tags VIP and VIP are considered different.

Cyrillic and Latin: both options are allowed.

Automatic creation:

  • If a tag is missing, it is created automatically.
  • If a user does not exist, a new user is created upon the call.
  • A call variant where a user is not created automatically is provided.

Trigger scenarios: assigning a tag launches a scenario configured in the Sailplay interface for the tag of the same name.

Remove Tags​

The method removes one or more tags from a user. Removal occurs for one or more tags passed separated by commas. Tags are removed based on an exact match. If a tag was assigned multiple times, it is enough to remove it once — it will completely disappear from the profile.

Get List of Tags​

The method allows returning a list of a client's tags. The tags parameter accepts an array of string values. If the tag list is not passed, all tags will be returned. The method returns detailed information about the last tag assignment event.

Bulk Tag Assignment​

Use the bulk tag assignment method to assign one or more tags to more than one client.

To manage the launching of trigger scenarios, use the query parameter run_chains:

  • 1 — launches trigger scenarios for the entire batch;
  • 0 — assigns tags without launching scenarios.

The request body structure is an array of clients and tags:

[
  {
    "user": {},
    "tags": []
  },
  {
    "user": {},
    "tags": []
  }
]

Client Identification​

The user parameter accepts one of the identifiers. Identifier types can be combined within a single request.

{
  "user": {
    "email": "mail@gmail.com"
  }
}
{
  "user": {
    "origin_user_id": "ID137813911"
  }
}
{
  "user": {
    "phone": "79998887766"
  }
}
{
  "user": {
    "id": 121823012
  }
}

Tags​

{
  "tags": [
    { "name": "Send message" },
    { "name": "In app" }
  ]
}

With additional parameters:

{
  "tags": [
    {
      "name": "Send message",
      "params": {
        "category": "Gift",
        "gift": "Free PIZZA"
      }
    }
  ]
}

Final Request Example​

[
  {
    "user": {
      "email": "mail@gmail.com"
    },
    "tags": [
      {
        "name": "Send message",
        "params": {
          "category": "Gift",
          "gift": "Free PIZZA"
        }
      }
    ]
  }
]

Response:

{
  "accepted": "ok"
}

The response means that the requests have been added to the queue for execution. The processing speed depends on the data volume.

Bulk Tag Removal​

The bulk tag removal method allows removing tags for more than one client. It accepts the same request body structure as the bulk assignment method.

Assign Tags Without Client Creation​

The method /api/v2/users/tags/assign/ assigns tags only to existing clients. If the client is not found, the request will be ignored. Parameters are similar to the /api/v2/users/tags/add/ method.