Context of this document: The Flip Sync API for users and channels

Please find the specifications for restricting interactions with the link below.

Flip API Documentation

Please note that the “Restrict Interactions” feature is only available after activation. Please get in touch with your contact person at Flip.

• The “Restrict Interactions” feature basically prevents you from starting a new chat. This is true for individual chats and for adding others to a chat group.
• If there is already a chat, you can use it, even if you are not allowed to talk to that person.
• This won't apply to creating posts, comments, or reactions.
• If the Employee Directory is active, it is still possible to see all the users in it.

Use cases for restricted interactions and how to get there

1. You must ensure that users are only contacted by relevant people who have a working-level relationship with them.
2. Because of the massive user count, you need to limit the communication possibilities for users, e.g., to let them contact the correct and relevant “Maximilian Meier” right away. This is to avoid problems with communication if the wrong people are contacted.
3. Your user base includes external employees, who should only be allowed to communicate with certain internal employees.

And, of course, many others.

Therefore, we introduced tags and rules:

• (User) tags can be assigned to the users via our Sync API.
• Rules can be created, read, updated, and deleted (CRUD) with our Sync API.

The Rules explain how users interact with certain tags. They consist of two parts: the conditions and the outcome. They also have a description and a unique identifier (UUID).

The user tags for restricted interactions

User tags are stored in the user information. A tag is a string with the following restrictions:

• the maximum length is 50, and
• can only contain the lower case, upper case, numbers, hyphen, and underscore.

The rules of restricted interactions

Rules have two parts: a condition and a result. The tags of the acting user are compared against the condition of the rules. If the condition is satisfied, the user is permitted to engage with users who possess one of the tags specified in the outcome.

Conditions of rules

The conditions for interactions are written in a small and descriptive language consisting of the following elements:

More examples:

• hasTag(A): select only users who have the tag A
• not(hasTag(A)): select only users who do not have the tag A
• any(hasTag(A), hasTag(B), all(hasTag(C), hasTag(D)): select only users who have the tag A or B or both of C and D.

Outcomes of rules

The outcome is a set of tags, of which the user must have at least one tag for the rule to be applied.

• A: Users with the tag A
• A, B: User with either the tag A or B

How to apply rules

All rules are evaluated independently. If the restrict interactions feature is enabled, all interaction is forbidden. Interaction can only be allowed as an opt-in approach with rules. Once one rule allows an interaction during evaluation, no other rule can remove it. The outcome of the rules is not stored and will be re-evaluated.

The rules do not apply to existing chats. They only apply to new chats.

Example scenario and solution

Imagine a company with stores in Berlin, Munich, and Stuttgart. Therefore, we have the three tags Berlin, Munich and Stuttgart.

• Rule-1: As Stuttgart serves as the headquarters, any user from Stuttgart can initiate a chat with any user from Berlin, Munich, or Stuttgart itself.
• Rule-2: Users from the stores in Berlin and Munich are also allowed to chat with users from Stuttgart.
• Rule-3: Every user from Munich is also permitted to chat with colleagues from Munich.
• Rule-4: There are store managers with both tags, Berlin and Munich. Those users are also allowed to start a private chat with every user from Berlin and Munich.

Important: Since there must be an explicit rule for each user to allow interaction with other users, in this example, users from Berlin implicitly cannot interact with users from the same store in Berlin.

The rules and tags for the example scenario

The following table shows the users with a different set of tags.

Applying the rules of the first table to all the users gives the following results:

The API

Before learning about the API, it's essential to understand how tags and rules work. Please refer to the chapters and the example above.

Requirements

• To fully use the API for rules, you must add tags to the users via the Sync API.
• The API client used must have the scopes TAG_RULE_WRITE and TAG_RULE_READ. If you have problems, please contact your Flip rep.

Please find the API specification here:

Flip API Documentation

The Rules API consists of four basic endpoints:

1. Create a new rule
2. Get all rules
3. Update a rule by rule_id
4. Delete the rule by rule_id

Create a new rule

As stated before, if no rules are defined, no one can interact with each other.

A rule consists of a condition and an outcome. Optionally, a description can be added. The following rule is from the example.

Request

POST /sync/interaction-rules

{
  "condition": "any(hasTag(Berlin), hasTag(Munich))",
  "description": "Users from Berlin and Munich can interact with the users from Stuttgart.",
  "outcome": ["Stuttgart"]
}

Response

In the response, the rule_id is returned for updating and deleting.

{
  "condition": "any(hasTag(Berlin), hasTag(Munich))",
  "description": "Users from Berlin and Munich can interact with the users from Stuttgart.",
  "outcome": ["Stuttgart"],
	"rule_id": "728c1541-d6d1-4290-9a53-cdf01dd32d60"
}

Get all the rules

This endpoint can be used to get all existing rules with all attributes rule_id, condition, outcome, and description.

Request

GET /sync/interaction-rules

Response

{
	"rules": [
		{
			"rule_id": "728c1541-d6d1-4290-9a53-cdf01dd32d60",
			"condition": "any(hasTag(Berlin), hasTag(Munich))",
			"outcome": ["Stuttgart"],
			"description": "Users from Berlin and Munich can interact with the users from Stuttgart."
		},
		{
			"rule_id": "18f71bae-0498-4edc-8091-dc6720f4359e",
			"condition": "hasTag(Stuttgart)",
			"outcome": ["Berlin", "Munich", "Stuttgart"],
		}
	]
}

Update a rule by rule_id

The rule_id is required to update a rule. It is returned when creating the rule or when requesting all rules. This endpoint uses the PUT semantics, where all fields are updated with the given value, so it is always necessary to resend all values.

In the following example, we update the existing rule so that it applies in reverse - so the condition must be negated.

Request

PUT /sync/interaction-rules/728c1541-d6d1-4290-9a53-cdf01dd32d60
{
  "condition": "not(any(hasTag(Berlin), hasTag(Munich)))",
  "description": "All users NOT from Berlin or Munich can interact with the users from Stuttgart.",
  "outcome": ["Stuttgart"]
}

Response

{
	"rule_id": "728c1541-d6d1-4290-9a53-cdf01dd32d60",
	"condition": "not(any(hasTag(Berlin), hasTag(Munich)))",
  "description": "All users NOT from Berlin or Munich can interact with the users from Stuttgart.",
  "outcome": ["Stuttgart"]
}

Delete a rule by rule_id

The delete endpoint can delete the rule created by the rule_id.

DELETE /sync/interaction-rules/728c1541-d6d1-4290-9a53-cdf01dd32d60