Delivery Endpoints (Push Notifications)

Delivery endpoints identify end-user devices where a message is delivered as opposed to the model of a user requesting for messages via HTTP. A deliver endpoint is specific to the delivery mechanism being used. mitter.io currently supports FCM delivery endpoints for both the web and mobile and WebSockets for Web. A delivery endpoint is assigned to a user and one user can have multiple delivery endpoints of differing types.

When a message is sent to a channel, a list of users that have access to the message and should be receiving it is computed. Then the message is delivered to all the delivery endpoints that are registered against that user. mitter.io internally handles retrying failed messages and other implementation details of the delivery mechanisms, for instance, it automatically udpates the device registration token whenever the FCM upstream server instructs that the old token has expired and a new one is to be used. Developers can continue using the same semantics for message delivery that is provided by mitter.io at higher levels of abstractions like users, messages, channels etc.

The Delivery Endpoint Model

The base model of a delivery endpoint looks rather simple, it consists of a serialized format of the endpoint and the type:

{
    "serializedEndpoint": "fcm:dXA1kcigCPw:APA...",
    "endpointType": "fcm"
}

The serialized endpoint if it contains multiple parts to it must be stored in a canonical format such that it can be used as a lookup key for further operations.

For an FCM delivery endpoint, the model used is:

{
    "endpointType": "fcm",
    "registrationToken": "dXA1kcigCPw:APA..."
}

Note that the registration token does not contain the fcm prefix. This is a device token that is issued by both the web and mobile firebase SDKs. You will also need to setup Firebase credentials in your application for the messages to deliver. For more information refer to the LINK(Setting up firebase) section in the reference documentation.

Delivery Entities

Not only messages, but certain other entities, like TimelineEvents are also pushed to the relevant users to their endpoints. All entities differ slightly in their signature from their mitter counterparts.

Messages

A NewMessagePayload is delivered to a user that the user should be receiving as a part of their participation in a channel. A message model that is delivered looks like:

{
    "@type": "new-message-event",
    "message": {
        "messageId": "<message-id">,
        .. rest of the message object ..
    },
    "channelId": "<channel-id-of-the-message>"
}

Channel

A NewChannelPayload is delivered to a user whenever a user should be notified that a new channel is created. This is computed if a user happens to have read access to the channel, even if the user is not a participant. The model looks like:

{
    "@type": "new-channel-event",
    "channel": {
        "channelId": "<channel-id>",
        .. rest of the channel object ..
    }
}

Timeline Event

A NewMessageTimelineEvent is sent to a user with the same semantics as that of receiving a message. If a user is a target for receiving a message, they are also a target for every timeline event on that message. The model of that:

{
    "@type": "new-timeline-event",
    "timelineEvent": {
        "type": "mitter.mtet.SentTime",
        .. rest of the timeline event object
    },
    "messageId": "<message-id>"
}

FCM Delivery Specifics

The raw message that is sent over FCM confirms to the data shape that FCM requires:

{
    "data": "{\"@type\":\"new-message-event\", \"message\":{ .. } }",
    "registration_ids": ["device-token-a0", .. ],
    "notification": {
        "body": "notification body",
        "icon": "notification icon",
        "title": "notification title"
    }
}

Do note that the data field is a String, which means that the value of the field needs to be deserialized to one of the messaging pipeline payloads. The type of the sent payload is mentioned in the @type field of the deserialized value of the data field.

For the notification field, which is used by FCM to automatically display notifications on the user device, refer to the next section.

Cloud Notifications

FCM (and other delivery mechanisms) supports sending push notifications if the message that is sent to the device populates certain fields. In the case of FCM, the object notification needs to be set with values for body, title and icon. Since mitter messages do not offer direct access to it, you can use specific messageDatum objects with the dataType as cloud-notification to denote to the FCM delivery facilitator to push the data as a notification. For future mechanisms, this API will continue to be supported with a similar model.

To send a notification to a user, one can use a message body like:

{
    "payloadType": "mitter.mt.Text",
    "textRepresentation": "Axe is back!",
    "messageDatum": [
    {
        "dataType": "cloud-notification",
        "data": {
            "body": "Axe is back!",
            "icon": "axe-icon.png",
            "title": "Axe!"
        }
    }
}

All other mechanisms for delivery will receive this as a regular message, but on FCM and other push-based mechanisms will convert this to the appropriate format for sending out a push notification. In the case of FCM, this would look like:

{
    "data": "{\"@type\":\"new-message-event\",\"message\":{ .. } }",
    "registrationIds": [ .. ],
    "notification": {
        "body": "Axe is back!",
        "icon": "axe-icon.png",
        "title": "Axe!"
    }
}

Operations on Delivery Endpoints

Adding a New Endpoint

To register a new delivery endpoint, you can make a POST call. By default, only the user can register an endpoint for themselves and .system can do it for any user. This behavior currently cannot be overridden.

POST /v1/users/a1c222c7-94c1-4046-8e91-e6f45d9490b2/delivery-endpoints
{
    "endpointType": "fcm",
    "registrationToken": "dXA1kcigCPw:APA..."
}

On successful execution, this method returns a 204

204 No Content

For an authenticated user, they can register a device endpoint for themselves by calling /v1/users/me/delivery-endpoints.

Deleting an Endpoint

To delete an existing delivery endpoint, you can make a DELETE call. By default, only the user can register an endpoint for themselves and .system can do it for any user. This behavior currently cannot be overridden.

DELETE /v1/users/a1c222c7-94c1-4046-8e91-e6f45d9490b2/delivery-endpoints/dXA1..

On successful execution, the server returns 204

204 No Content