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 & Examples

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 wish to use for your function. Either AWS Credentials or ARN of an assumable role
Qualifier
optional qualifier for your AWS Lambda function
Source
Choose which of Message or Presence events on channels should activate this Reactor Event Rule.
Channel filter
An optional filter, which allows the Rule to be applied to a restricted set of channels. This can be specified as a regular expression, allowing for swathes of channels to be used


If the Rule is using AWS Credentials to authenticate, it will also have the following options:

AWS Credentials
a key:value pair which match your AWS credentials


If the Rule is using ARN of an assumable role to authenticate, it will also have the following options:

Assume Role ARN
your ARN which will work for this AWS Lambda function

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, namely “channel.message” or “channel.presence
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.

{
  "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.

{
  "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.FT1yOA:HeBwcnNfYxzuxU4z" \
          -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.FT1yOA:HeBwcnNfYxzuxU4z', clientId: 'bob' });
channel = realtime.channels.get('some_channel');
channel.presence.enter('some data');
realtime = new Ably.Realtime({ key: 'xVLyHw.FT1yOA:HeBwcnNfYxzuxU4z', 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