Example AWS Lambda function, triggered by the Reactor, that publishes another message back to Ably

Author: franrob-projects

src/pages/docs/platform/integrations/webhooks/lambda.mdx

@@ -112,3 +112,60 @@ Ably invokes Lambda functions asynchronously using the `event` invocation type.
 Lambda functions might run multiple times for the same Ably event. Design functions to handle this by making them idempotent or checking for duplicate processing.
 
 You can configure retry behavior in your AWS Lambda console under the function's asynchronous invocation settings. See the [AWS Lambda documentation](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html#invocation-async-errors) for details on adjusting retry settings.
+
+## Routing Messages with Integration Rules <a id="routing"/>
+
+When an Integration Rule triggers your Lambda function, it can process the incoming message and publish a response back to Ably. This enables message routing and transformation patterns across your channels.
+
+### Lambda Function Setup
+
+Your Lambda function must be packaged with the Ably client library and uploaded to AWS Lambda as a zip file.
+
+For a complete example package, see: https://github.com/ably/example-lambda-function
+
+### Implementation
+
+<Code>
+```javascript
+'use strict';
+
+const Ably = require('ably');
+const inspect = require('util').inspect;
+
+exports.handler = (event, context, callback) => {
+  console.log("Received the following event from Ably: ", inspect(event));
+
+  // Parse the incoming event
+  // With enveloping enabled: event contains 'source', 'appId', 'channel',
+  // 'site', 'ruleId', and 'messages' or 'presence' arrays
+  // With enveloping disabled: event is the message data directly
+  const details = JSON.parse(event.messages[0].data);
+
+  // Use Ably.Rest for efficient REST-based publishing
+  // This avoids the overhead of establishing a WebSocket connection
+  const ably = new Ably.Rest({ key: '<YOUR_API_KEY>' });
+
+  // Get the target channel and publish the response
+  // Important: Do not publish to a channel that triggers this same rule
+  // to avoid infinite loops
+  const channel = ably.channels.get('<TARGET_CHANNEL_NAME>');
+
+  channel.publish('lambdaresponse', 'success', (err) => {
+    if(err) {
+      console.log("Error publishing back to ably:", inspect(err));
+      callback(err);
+    } else {
+      // Only call callback() after publish completes
+      // to ensure the HTTP request finishes before function execution ends
+      callback(null, 'success');
+    }
+  });
+};
+```
+</Code>
+
+### Important Considerations
+
+**Avoiding Infinite Loops**: Never publish messages to a channel that would trigger the same Integration Rule. Always ensure your target channel is different from the source channel or configure your Integration Rule with appropriate channel filters.
+
+**Using REST vs. Realtime**: The example uses `Ably.Rest` instead of `Ably.Realtime` because REST API is more efficient for one-off publishing operations and avoids WebSocket connection overhead in Lambda's stateless environment.