Concepts

Core concepts of the mitter platform

Application

From Mitter's perspective, an application is an entity that defines a strict data boundary. All API calls are constrained by this condition of tenancy and an application identifier (or proof of authenticity) must be provided to perform an operation. A Mitter.io application would ideally map to an actual application (that you are building). If you have an application ported on multiple platforms (say, Android and the Web), you must continue using the same Mitter.io application so that your users can seamlessly communicate across these platforms.

User

A User is a special entity that executes specific operations, with the most significant being when acting as a sender of messages. A User is strictly namespaced within an Application, and permissions regarding viewing and participation are tied at a user level.

User Locator

A User Locator is a globally-unique identifier used to identify a User, for instance, an 'email' or a 'phone number'. User locators are used as look-up keys for users across a variety of user-related APIs. Whenever expressing a user locator, it needs to be prefixed by the type of locator that is being used unless the user locator is provided as an entity.

The standard prefix for emails is email and for phone numbers is tele. Emails are expected to be as per the format specified in RFC 822 and phone numbers must be provided in the E164 format, always prefixed by a country-code specifier.

Channel

A Channel, simply put, is a collection of Messages, Timeline Events (see below) and Users. A User associated with a Channel is called a 'participant'. There are multiple types of Channels that are supported, with support coming soon for custom Channels types as well. Every channel that is created is assigned a ruleset. The ruleset defines the constraints of the channel. An example ruleset would be io.mitter.ruleset.chats.DirectMessage. This ruleset enforces the following constraints:

1. This Channel can have exactly two participants at any given time.

2. All participants have to be provided at the time of creation of the Channel.

3. No participant's status can be changed to any status other than Active.

4. No participants can be added/removed/replaced.

Other rulesets provide for other common use-cases around channels. In the near future, mitter.io will be providing for ways to define such rules in an expressive syntax, which will allow for such rules to be set by the developer and create custom rulesets.

Message

A Message is simply a communication sent from a user (called a sender) to a Channel. A message may be of multiple types - images, text, video etc., and even custom payloads. A Message can be sent by a sender to a Channel if and only if the sender is a participant in the channel.

A message in mitter.io in terms of the model and handling is a complex entity. Do refer to the reference documentation on messages for a more detailed description of messages within Mitter.io.

Timeline Event

A Timeline Event denotes some event having occurred on an entity. Currently, Timeline Events can be attached to Messages and Channels. They simply contain a label and timestamp. You can use Message Timeline Events to implement Message receipts (sent, read, delivered, etc.) and Channel Timeline Events to implement Channel State (User left/joined channel, etc.)

Profile

A Profile is a set of key-value pairs that can be associated with entities. You can define custom attributes and some rules around them (like canBeEmtpy, allowedContentTypes) and set values for them. For instance, you can create an attribute called GravatarUrl for Users, and you can then set a value for this attribute for a User with an API like:

POST /v1/users/{userId}/profile
{
    "key": "GravatarUrl".
    "value": "www.gravatar.com/avatar/<myemailhash>"
}

Currently, Profiles are supported only on Users, but will soon be extended to Channels as well.