Real-Time Events

You'll find an overview of all the real-time event channels we support as a part of our SDK's capabilities in this section. We support Google Pub/Sub and Webhooks to enable you to utilise real time events within your app.

Messaging States

Ideally, you should be able to map the state exposed by the Chat SDK directly to your application UI. You would only need to send the right actions to the SDK, and any update to the state will be emitted to you via LiveObject updates.

All methods in our Chat SDK are designed to return synchronously, and will automatically establish a connection to the server when needed and send the request to the server. If the server is not available, our Chat SDK will queue up any requests and will automatically try to connect to the server with exponential backoff.

In order to provide the best user experience, the Chat SDK will automatically persist its state to the user device's disk. All queries that return a LiveObject will use a cache then network strategy in order to ensure that relevant data is always presented to the user.

Live Objects

LiveObject represents a query that is always updated in real-time, informing you whenever the data in the query changes. It encapsulates all logic around using local cache, querying from the network, and receiving live events from the network into one simple interface.

Google Pub/Sub

Our Pub/Sub requires a Google Cloud Service Account, the user can begin receiving events by sending their key.json credential file to Amity along with the Topic Name that they wish for the event payloads to communicate to.

Events

Our PubSub currently supports sending payloads for the following events:

Event name	Description
message.didCreate	Anytime a user in your network creates a message
message.didDelete	Anytime a message is deleted
message.didUpdate	Anytime a message is updated
channel.didCreate	Anytime a channel is created
channel.didJoin	Anytime a user joins a channel
channel.didAddUsers	Anytime a user adds other users to a channel
channel.didClose	Anytime a channel is closed
channel.didLeave	Any time a user leaves a channel
channel.didUpdate	Anytime a channel is updated
channel.didRemoveUsers	Anytime a user is removed from a channel
channel.didUpdateMeta	Anytime a channel's metadata is updated
channel.didBan	Anytime a user is banned from a channel
moderation.didBan	Anytime message that contains a blocklisted word is blocked
community.didCreate	Anytime a community is created
community.didUpdate	Anytime a community is updated
community.didDelete	Anytime a community is deleted
community.didJoin	Anytime a user joins a community
community.didLeave	Anytime a user leaves a community
community.didAddUsers	Anytime a user is added to a community
community.didRemoveUsers	Anytime a user is removed from a community
community.didBan	Anytime a user is banned from a community
community.didUnban	Anytime a user is unbanned from a community
post.didCreate	Anytime a post is created
post.didUpdate	Anytime a post is updated
post.didDelete	Anytime a post is deleted
post.didFlag	Anytime a post is flagged
post.didUnflag	Anytime a post is un-flagged
post.didAddReaction	Anytime a reaction is added to a post
post.didRemoveReaction	Anytime a reaction is removed from a post
comment.didCreate	Anytime a comment is created without a parentID
comment.didUpdate	Anytime a comment is updated
comment.didDelete	Anytime a comment is deleted
comment.didFlag	Anytime a comment is flagged
comment.didUnflag	Anytime a comment is un-flagged
comment.didAddReaction	Anytime a reaction is added to a comment
comment.didRemoveReaction	Anytime a reaction is removed from a comment
comment.didReply	Anytime a comment has a reply

Webhook

Overview

When an event is triggered, an HTTP POST payload is sent to the Webhook's configured URL. Webhooks can serve various purposes such as creating push notifications, backup logging or even building external applications based on Webhook events.

• Admin users can create new Webhooks in admin panel by using URL

• Admin users can delete selected Webhooks in admin panel as well

• We support unlimited Webhooks however we have a limitation per network

• We recommend having no more than 10 Webhooks/network for stable performance

• All Webhooks will be triggered by events, unfortunately we do not allow event customization at this moment

• You must detect a secretKey value in the header section (X-Eko-Signature), which will be received when the system sends a Webhook. This is done in order to verify that a request was sent by us

• The URL must support POST methods only, unfortunately we do not have any Webhook testing currently available; though this will be coming soon!

Events

Amity does not currently support subscribing to specific events just yet. All the following events will trigger a server response in the form of an HTTP POST payload to the webhook's configured URL.

Event name	Description
message.didCreate	any time a user in your network creates a message
channel.didCreate	any time a channel is created
channel.didJoin	any time a user joins a channel
channel.didAddUsers	any time a user adds other users to a channel

Payloads

Though each event has a specific payload format with the relevant event information; they all use the same object structure with the following keys:

Header	Description
requestId	a unique identifier of the post request. You can use it to trace back to our Amity server when there is an issue
webhookId	the subscription iD of the webhook registered to our server.
event	an event name that triggers this POST request
data	the relevant event information that relates to the trigger event. Each event has specific payload format.

Delivery Headers

The HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain the following headers:

Header	Description
x-eko-signature	the HMAC hex digest of the response body.The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.

Example Delivery

POST /youurl HTTP/1.1
Host: localhost:4567
X-EKO-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
User-Agent: node-superagent/4.0.0
Content-Type: application/json
Content-Length: 442
{
  "requestId": "5c01045b8350df000fdff589",
  "webhookId": "5c0103408350df000fdff588",
  "event": "channel.didCreate",
  "data": {
    "userIds": ["A"],
    "channel": {
      "isDistinct": false,
      "type": "standard",
      "metadata": {},
      "tags": [],
      "isMuted": false,
      "lastActivity": "2018-11-30T09:35:23.816Z",
      "updatedAt": "2018-11-30T09:35:23.815Z",
      "createdAt": "2018-11-30T09:35:23.815Z",
      "isRateLimited": false,
      "rateLimitWindow": 1000,
      "channelId": "testWebhook",
      "memberCount": 0,
      "messageCount": 0
    },
    "users": [
      {
        "displayName": "A",
        "updatedAt": "2018-11-30T11:39:19.615Z",
        "createdAt": "2018-11-01T09:33:57.811Z",
        "userId": "A",
        "roles": [],
        "flagCount": 0,
        "hashflag": { "bits": 0, "hashes": 0, "hash": [] }
      }
    ]
  }
}