AWS Lambda Functions

As part of Reactor Events, it is possible to integrate with various systems.

AWS Lambda Functions provide event-driven serverless compute functions which allow users to easily run code whenever events are sent to it. These can be very useful for integrating into various other AWS systems.

Tutorials

If you would like to just dive in and see an example of this being implemented, then take a look at our AWS Lambda tutorial.

For more details on the specifics of how Reactor Events and our integrations work, check out our Reactor Events documentation.

Rule fields

AWS Region
The region you chose for your AWS Lambda function.
Function Name
The name you gave your AWS Lambda function.
AWS Authentication Scheme
the authentication scheme you use for your function. Either AWS Credentials or ARN of an assumable role. See the Ably AWS authentication documentation.
Qualifier
optional qualifier for your AWS Lambda function.
Source
Choose which of channel.message, channel.presence, channel.lifecycle, or channel.occupancy events on channels should activate this event rule.
Channel filter
An optional filter on channel name, to restrict the channels the rule applies to. Use a regular expression to match multiple channels.

Restrictions

At present, it is not possible to batch messages to AWS Lambda Functions, nor can messages be encoded in anything besides JSON.

Examples

Enveloped event payloads

Each enveloped message will have the following fields:

source
the source for the webhook, which will be one of channel.message, channel.presence, channel.lifecycle, or channel.occupancy
appId
the Ably app this message came from
channel
the Ably channel where the event occurred
site
the Ably datacenter which sent the message
timestamp
a timestamp represented as milliseconds since the epoch for the presence event

In addition, it will contain another field which will contain the actual message, which is named according to the message type.

Enveloped message events

For message events, the messages array contains a raw message.

The following is an example of an enveloped message payload:

{
  "source": "channel.message",
  "appId": "aBCdEf",
  "channel": "channel-name",
  "site": "eu-central-1-A",
  "ruleId": "1-a2Bc",
  "messages": [{
    "id": "ABcDefgHIj:1:0",
    "connectionId": "ABcDefgHIj",
    "timestamp": 1123145678900,
    "data": "some message data",
    "name": "my message name"
  }]
}
Decoding enveloped messages

Messages sent over the realtime service are automatically decoded into Message objects by the Ably client library. With webhooks you need to to do this explicitly, using Message.fromEncodedArray on the messages array, or Message.fromEncoded on an individual member of that array. This will transform them into an array of Message objects (or in the case of fromEncoded, an individual Message). This has several advantages, e.g.:

  • It will fully decode any data (using the encoding) back into the same datatype that it was sent in (or an equivalent in each client library’s language)
  • If you are using encryption, you can pass your encryption key to the method and it will decrypt the data for you

We recommend you do this for all messages you receive over webhooks. For example (using ably-js):

const messages = Ably.Realtime.Message.fromEncodedArray(item.messages);
messages.forEach((message) => {
  console.log(message.toString());
})

Enveloped presence events

For presence events, the presence array contains a raw presence message.

The following is an example of of an enveloped message payload with a presence array:

{
  "source": "channel.message",
  "appId": "aBCdEf",
  "channel": "channel-name",
  "site": "eu-central-1-A",
  "ruleId": "1-a2Bc",
  "presence": [{
    "id": "abCdEFgHIJ:1:0",
    "clientId": "bob",
    "connectionId": "Ab1CDE2FGh",
    "timestamp": 1582270137276,
    "data": "some data in the presence object",
    "action": 4
  }]
}
Decoding enveloped presence messages

Presence messages sent over the realtime service are automatically decoded into PresenceMessage objects by the Ably client library. With webhooks you need to to do this explicitly, using PresenceMessage.fromEncodedArray on the presence array, or PresenceMessage.fromEncoded on an individual member of that array. This will transform them into an array of PresenceMessage objects (or in the case of fromEncoded, an individual PresenceMessage). This has several advantages, e.g.:

  • It will decode the (numerical) action into a Presence action string (such as “enter”, “update”, or “leave”)
  • It will fully decode any data (using the encoding) back into the same datatype that it was sent in (or an equivalent in each client library’s language)
  • If you are using encryption, you can pass your encryption key to the method and it will decrypt the data for you

We recommend you do this for all presence messages you receive over webhooks. For example (using ably-js):

const messages = Ably.Realtime.PresenceMessage.fromEncodedArray(item.messages);
messages.forEach((message) => {
  console.log(message.toString());
})

Non-enveloped event payloads

Non-enveloped message events

For message events, there will be the additional headers:

x-ably-message-name
The name of the Message

The payload will contain the data of the Message.

For example, if you sent the following curl message, which sends a JSON message to the channel my_channel:

curl -X POST https://rest.ably.io/channels/my_channel/messages \
          -u "xVLyHw.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec" \
          -H "Content-Type: application/json" \
          --data '{ "name": "publish", "data": "example" }'

The x-ably-message-name header would be publish, and the payload would be example.

Non-enveloped presence events

For Presence events, there will be the additional headers:

x-ably-message-action
the action performed by the event (update, enter, leave)

The payload will contain the data of the Presence message.

For example, if a client enters a channel’s presence with the following code:

realtime = new Ably.Realtime({ key: 'xVLyHw.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec', clientId: 'bob' });
channel = realtime.channels.get('some_channel');
channel.presence.enter('some data');
realtime = new Ably.Realtime({ key: 'xVLyHw.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec', clientId: 'bob' });
channel = realtime.channels.get('some_channel');
channel.presence.enter('some data');

Then the x-ably-message-action would be enter, the x-ably-message-client-id would be “bob”, and the payload would be “some data”.


API reference
Documentation

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.