From 14f6fdd9a5dcfc8c0d3dd922e4c936aa37df9bf9 Mon Sep 17 00:00:00 2001 From: owenpearson Date: Thu, 19 Mar 2026 11:34:04 +0000 Subject: [PATCH] add pickers for rule creation with control API and CLI examples --- src/components/Layout/MDXWrapper.tsx | 3 + src/components/Layout/mdx/MethodPicker.tsx | 67 +++++++++++++++++++ src/pages/docs/channels/index.mdx | 46 ++++++++++++- src/pages/docs/livesync/mongodb/index.mdx | 43 ++++++++++-- src/pages/docs/livesync/postgres/index.mdx | 43 ++++++++++-- src/pages/docs/messages/annotations.mdx | 48 +++++++++++-- src/pages/docs/messages/batch.mdx | 46 ++++++++++++- src/pages/docs/messages/index.mdx | 48 ++++++++++++- src/pages/docs/messages/updates-deletes.mdx | 40 +++++++++++ .../docs/platform/integrations/queues.mdx | 54 ++++++++++++++- .../platform/integrations/streaming/amqp.mdx | 39 ++++++++++- .../platform/integrations/streaming/kafka.mdx | 44 +++++++++++- .../integrations/streaming/kinesis.mdx | 42 +++++++++++- .../integrations/streaming/pulsar.mdx | 41 +++++++++++- .../platform/integrations/streaming/sqs.mdx | 42 +++++++++++- .../platform/integrations/webhooks/azure.mdx | 37 +++++++++- .../integrations/webhooks/cloudflare.mdx | 37 +++++++++- .../integrations/webhooks/gcp-function.mdx | 38 ++++++++++- .../integrations/webhooks/generic.mdx | 57 +++++++++++++++- .../platform/integrations/webhooks/ifttt.mdx | 35 +++++++++- .../platform/integrations/webhooks/lambda.mdx | 40 ++++++++++- .../platform/integrations/webhooks/zapier.mdx | 34 +++++++++- 22 files changed, 874 insertions(+), 50 deletions(-) create mode 100644 src/components/Layout/mdx/MethodPicker.tsx diff --git a/src/components/Layout/MDXWrapper.tsx b/src/components/Layout/MDXWrapper.tsx index 8a1fddce6c..14ef5f7a7f 100644 --- a/src/components/Layout/MDXWrapper.tsx +++ b/src/components/Layout/MDXWrapper.tsx @@ -22,6 +22,7 @@ import { Tiles } from './mdx/tiles'; import { PageHeader } from './mdx/PageHeader'; import Admonition from './mdx/Admonition'; import { MethodSignature } from './mdx/MethodSignature'; +import { MethodPicker, Method } from './mdx/MethodPicker'; import { Frontmatter, PageContextType } from './Layout'; import { ActivePage } from './utils/nav'; @@ -339,6 +340,8 @@ const MDXWrapper: React.FC = ({ children, pageContext, location td: Table.Cell, Tiles, MethodSignature, + MethodPicker, + Method, }} > diff --git a/src/components/Layout/mdx/MethodPicker.tsx b/src/components/Layout/mdx/MethodPicker.tsx new file mode 100644 index 0000000000..c085405906 --- /dev/null +++ b/src/components/Layout/mdx/MethodPicker.tsx @@ -0,0 +1,67 @@ +import React, { useState, createContext, useContext, isValidElement, ReactNode } from 'react'; +import cn from '@ably/ui/core/utils/cn'; + +type MethodContextType = { + activeMethod: string; +}; + +const MethodContext = createContext(undefined); + +const METHOD_LABELS: Record = { + dashboard: 'Dashboard', + 'control-api': 'Control API', + cli: 'Ably CLI', +}; + +interface MethodProps { + value: string; + children: ReactNode; +} + +export const Method: React.FC = ({ value, children }) => { + const context = useContext(MethodContext); + if (!context) { + return null; + } + return context.activeMethod === value ? <>{children} : null; +}; + +interface MethodPickerProps { + children: ReactNode; +} + +export const MethodPicker: React.FC = ({ children }) => { + // Extract method values from Method children + const methods: string[] = []; + React.Children.forEach(children, (child) => { + if (isValidElement(child) && child.props.value) { + methods.push(child.props.value); + } + }); + + const [activeMethod, setActiveMethod] = useState(methods[0] ?? 'dashboard'); + + return ( + +
+
+ {methods.map((method) => ( + + ))} +
+
{children}
+
+ + ); +}; diff --git a/src/pages/docs/channels/index.mdx b/src/pages/docs/channels/index.mdx index 1cf50357d0..b6158849da 100644 --- a/src/pages/docs/channels/index.mdx +++ b/src/pages/docs/channels/index.mdx @@ -202,7 +202,10 @@ The rules related to enabling features are: | Message conflation | If enabled, messages are aggregated over a set period of time and evaluated against a conflation key. All but the latest message for each conflation key value will be discarded, and the resulting message, or messages, will be delivered to subscribers as a single batch once the period of time elapses. [Message conflation](/docs/messages#conflation) reduces costs in high-throughput scenarios by removing redundant and outdated messages. | | Message annotations, updates, deletes, and appends | If enabled, allows message "annotations":/docs/messages/annotations to be used, as well as updates, deletes, and appends to be published to messages. Note that these features are currently in public preview. When this feature is enabled, messages will be "persisted":/docs/storage-history/storage#all-message-persistence (necessary in order from them later be annotated or updated), and "continuous history":/docs/storage-history/history#continuous-history features will not work. -To set a rule in the Ably dashboard: +To set a rule: + + + 1. Sign in to your Ably account. 2. Select an app. @@ -211,6 +214,47 @@ To set a rule in the Ably dashboard: 5. Select channel name or namespace to apply rules to. 6. Check required rules. + + + +Use the [Control API](/docs/platform/account/control-api) to create a channel rule by sending a `POST` request to `/apps/{app_id}/namespaces`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "my-namespace", + "persisted": true, + "persistLast": false, + "pushEnabled": false, + "tlsOnly": false, + "authenticated": false + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule: + + +```shell +ably apps rules create \ + --name "my-namespace" \ + --persisted +``` + + +Run `ably apps rules create --help` for a full list of available options. + + + + ## Channel history Channel [history](/docs/storage-history/history) enables clients to retrieve messages that have been previously published on the channel. Messages can be retrieved from history for up to 72 hours in the past, depending on the [persistence](/docs/storage-history/storage) configured for the channel. diff --git a/src/pages/docs/livesync/mongodb/index.mdx b/src/pages/docs/livesync/mongodb/index.mdx index 3adc1b20b1..9145039ef7 100644 --- a/src/pages/docs/livesync/mongodb/index.mdx +++ b/src/pages/docs/livesync/mongodb/index.mdx @@ -24,17 +24,46 @@ When a change event is received over the Change Streams API it is published to a You first need to create an integration rule in order to sync your MongoDB instance with Ably. -There are two ways to create a MongoDB database connector rule: - -1. Using the [Ably Dashboard](https://ably.com/dashboard). -2. Using the [Control API](/docs/platform/account/control-api). + + To create a rule in your [dashboard](https://ably.com/dashboard): 1. Log in and select the application you wish to use. -2. Click the *Integrations* tab. -3. Click the *New Integration Rule* button. -4. Choose *MongoDB* from the list. +2. Click the **Integrations** tab. +3. Click the **New Integration Rule** button. +4. Choose **MongoDB** from the list. +5. Configure the [rule settings](#config). + + + + +Use the [Control API](/docs/platform/account/control-api) to create a MongoDB rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "ingress/mongodb", + "target": { + "url": "mongodb://user:pass@myhost.com", + "database": "my-database", + "collection": "my-collection", + "pipeline": "[{\"$set\": {\"_ablyChannel\": \"myDocuments\"}}]", + "fullDocument": "off", + "fullDocumentBeforeChange": "off", + "primarySite": "us-east-1-A" + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Rule configuration diff --git a/src/pages/docs/livesync/postgres/index.mdx b/src/pages/docs/livesync/postgres/index.mdx index d1741f2191..00cc020f14 100644 --- a/src/pages/docs/livesync/postgres/index.mdx +++ b/src/pages/docs/livesync/postgres/index.mdx @@ -34,15 +34,46 @@ By writing change events to the outbox table within the same database transactio ### Creating the rule -There are two ways to create a Postgres integration rule: -1. Using the [Ably Dashboard](https://ably.com/dashboard). -2. Using the [Control API](/docs/platform/account/control-api). + + To create a rule in your [dashboard](https://ably.com/dashboard): + 1. Login and select the application you wish to use. -2. Click the *Integrations* tab. -3. Click the *New Integration Rule* button. -4. Choose *Postgres* from the list. +2. Click the **Integrations** tab. +3. Click the **New Integration Rule** button. +4. Choose **Postgres** from the list. +5. Configure the [rule settings](#configure). + + + + +Use the [Control API](/docs/platform/account/control-api) to create a Postgres rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "ingress-postgres-outbox", + "target": { + "url": "postgres://user:password@example.com:5432/your-database-name", + "outboxTableSchema": "public", + "outboxTableName": "outbox", + "nodesTableSchema": "public", + "nodesTableName": "nodes", + "sslMode": "prefer", + "primarySite": "us-east-1-A" + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Rule configuration diff --git a/src/pages/docs/messages/annotations.mdx b/src/pages/docs/messages/annotations.mdx index 4931ae8331..765f345d2f 100644 --- a/src/pages/docs/messages/annotations.mdx +++ b/src/pages/docs/messages/annotations.mdx @@ -27,11 +27,51 @@ When message annotations are enabled, messages are [persisted](/docs/storage-his [Continuous history](/docs/storage-history/history#continuous-history) features are not supported. Be aware that if you are currently using continuous history and enable annotations, updates, deletes, and appends, continuous history will no longer function. + + + 1. Go to the **Settings** tab of an app in your dashboard. -3. Under [rules](/docs/channels#rules), click **Add new rule**. -4. Enter the channel name or channel namespace on which to enable message annotations. -5. Check **Message annotations, updates, deletes, and appends** to enable message annotations. -6. Click **Create rule** to save. +2. Under [rules](/docs/channels#rules), click **Add new rule**. +3. Enter the channel name or channel namespace on which to enable message annotations. +4. Check **Message annotations, updates, deletes, and appends** to enable message annotations. +5. Click **Create rule** to save. + + + + +Use the [Control API](/docs/platform/account/control-api) to create a channel rule with annotations enabled by sending a `POST` request to `/apps/{app_id}/namespaces`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "my-namespace", + "mutableMessages": true + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule with annotations enabled: + + +```shell +ably apps rules create \ + --name "my-namespace" \ + --mutable-messages +``` + + +Run `ably apps rules create --help` for a full list of available options. + + + ## Annotation types diff --git a/src/pages/docs/messages/batch.mdx b/src/pages/docs/messages/batch.mdx index e5866de3c3..63d557ac80 100644 --- a/src/pages/docs/messages/batch.mdx +++ b/src/pages/docs/messages/batch.mdx @@ -27,16 +27,58 @@ When configuring server-side batching, you need to configure a batching interval Each batch can contain up to 200 messages by count or total data size. For example, if you have 210 messages, they will be split into two batches: one with 200 messages and another with 10 messages. If the combined data size of 200 messages exceeds the data limit, the excess will be allocated to a new batch as separate messages. -Use the following steps to configure server-side batching for a channel, or channel namespace: +Use one of the following methods to configure server-side batching for a channel or channel namespace: + + + 1. On your [dashboard](https://ably.com/accounts/any), select one of your apps. 2. Go to **Settings**. 3. Under [rules](/docs/channels#rules), click **Add new rule**. -4. Enter the channel name, or channel namespace to apply server-side batching to. +4. Enter the channel name or channel namespace to apply server-side batching to. 5. Check **Server-side batching enabled**. 6. Choose a batching interval over which to aggregate messages. 7. Click **Create rule** to save. + + + +Use the [Control API](/docs/platform/account/control-api) to create a channel rule with server-side batching by sending a `POST` request to `/apps/{app_id}/namespaces`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "my-namespace", + "batchingEnabled": true, + "batchingInterval": 100 + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule with server-side batching: + + +```shell +ably apps rules create \ + --name "my-namespace" \ + --batching-enabled \ + --batching-interval 100 +``` + + +Run `ably apps rules create --help` for a full list of available options. + + + + diff --git a/src/pages/docs/messages/index.mdx b/src/pages/docs/messages/index.mdx index 40db33b0ac..7ef4e106d3 100644 --- a/src/pages/docs/messages/index.mdx +++ b/src/pages/docs/messages/index.mdx @@ -74,17 +74,61 @@ In these instances the frequency of updates for the subscriber are of less impor When configuring message conflation, you need to set a conflation interval, in milliseconds. Messages sent to Ably during this interval are temporarily held and assessed against the [conflation key](#routing). Once the interval elapses, the latest version of each message for a unique conflation key value will be delivered to subscribers as a single batch. -Use the following steps to configure message conflation for a channel, or channel namespace: +Use one of the following methods to configure message conflation for a channel or channel namespace: + + + 1. On your [dashboard](https://ably.com/accounts/any), select one of your apps. 2. Go to **Settings**. 3. Under [rules](/docs/channels#rules), click **Add new rule**. -4. Enter the channel name, or channel namespace to apply message conflation to. +4. Enter the channel name or channel namespace to apply message conflation to. 5. Check **Conflation enabled**. 6. Choose a conflation interval over which to aggregate messages. 7. Enter a [conflation key](#routing) to assess messages against. 8. Click **Create rule** to save. + + + +Use the [Control API](/docs/platform/account/control-api) to create a channel rule with message conflation by sending a `POST` request to `/apps/{app_id}/namespaces`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "my-namespace", + "conflationEnabled": true, + "conflationInterval": 100, + "conflationKey": "name" + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule with message conflation: + + +```shell +ably apps rules create \ + --name "my-namespace" \ + --conflation-enabled \ + --conflation-interval 100 \ + --conflation-key "name" +``` + + +Run `ably apps rules create --help` for a full list of available options. + + + + diff --git a/src/pages/docs/messages/updates-deletes.mdx b/src/pages/docs/messages/updates-deletes.mdx index 3c9cdf4757..4b1b79ed44 100644 --- a/src/pages/docs/messages/updates-deletes.mdx +++ b/src/pages/docs/messages/updates-deletes.mdx @@ -31,12 +31,52 @@ When message updates and deletes are enabled, messages are [persisted](/docs/sto [Continuous history](/docs/storage-history/history#continuous-history) features are not yet supported. Be aware that for now, if you are currently using continuous history and enable annotations, updates, deletes, and appends, continuous history will no longer function. + + + 1. Go to the **Settings** tab of an app in your dashboard. 2. Under [rules](/docs/channels#rules), click **Add new rule**. 3. Enter the channel name or channel namespace on which to enable message updates and deletes. 4. Check **Message annotations, updates, deletes, and appends** to enable the feature. 5. Click **Create rule** to save. + + + +Use the [Control API](/docs/platform/account/control-api) to create a channel rule with updates and deletes enabled by sending a `POST` request to `/apps/{app_id}/namespaces`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/namespaces \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "id": "my-namespace", + "mutableMessages": true + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a channel rule with updates and deletes enabled: + + +```shell +ably apps rules create \ + --name "my-namespace" \ + --mutable-messages +``` + + +Run `ably apps rules create --help` for a full list of available options. + + + + ## Update a message To update an existing message, use the `updateMessage()` method on a REST or realtime channel. The published update will have an `action` of `message.update`. diff --git a/src/pages/docs/platform/integrations/queues.mdx b/src/pages/docs/platform/integrations/queues.mdx index 8750aef3c9..98679f2d2a 100644 --- a/src/pages/docs/platform/integrations/queues.mdx +++ b/src/pages/docs/platform/integrations/queues.mdx @@ -98,19 +98,67 @@ This process ensures no message loss during the transition. After you provision a Queue, create one or more Queue rules to republish messages, presence events, or channel events from channels into that queue. -The following steps explain how to set up a queue rule: + + 1. Go to the **Integrations** tab of an app in your Ably [dashboard.](https://ably.com/accounts/any/apps/any/integrations) 2. Click **New Integration Rule**. 3. In the **Select your rule type** section, choose Queue. 4. In the **Choose queue** dropdown, select the queue you want to send data to. -5. (Optional) Add custom Headers as key:value pairs to include metadata. -** Click **Another header** to add additional headers. +5. (Optional) Add custom Headers as key:value pairs to include metadata. Click **Another header** to add additional headers. 6. In the [**Source**](/docs/platform/integrations/webhooks#sources) dropdown, select which type of Ably event should trigger the rule. 7. (Optional) Add a [**Channel Filter**](/docs/platform/integrations/webhooks#channel-filter) using a regular expression to apply the rule to specific channels. Leave empty to apply to all. 8. Choose an [**Encoding**](/docs/platform/integrations/webhooks#encoding) format. 9. Click **Create** to finish setting up the rule. + + + +Use the [Control API](/docs/platform/account/control-api) to create a queue rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "amqp", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "queueId": "your-app-id:your-queue-name", + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a queue rule: + + +```shell +ably integrations create \ + --rule-type amqp \ + --source-type channel.message +``` + + + + + + + ### Queue stats Provisioned queues are visible in your app [dashboard](https://ably.com/accounts/any/apps/any/queues) and provide realtime stats for the current state of each queue. diff --git a/src/pages/docs/platform/integrations/streaming/amqp.mdx b/src/pages/docs/platform/integrations/streaming/amqp.mdx index dc013fc8f1..94ec8b7cc9 100644 --- a/src/pages/docs/platform/integrations/streaming/amqp.mdx +++ b/src/pages/docs/platform/integrations/streaming/amqp.mdx @@ -11,7 +11,10 @@ redirect_from: ## Create an AMQP integration -To create an AMQP integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create an AMQP integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with AMQP. 2. Click the **Integrations** tab. @@ -21,7 +24,39 @@ To create an AMQP integration in your [dashboard:](https://ably.com/dashboard/an 6. Configure the AMQP [settings](#settings). 7. Click **Create**. -You can also create an AMQP integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create an AMQP rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "amqp/external", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "url": "amqps://username:password@broker.example.com/vhost", + "routingKey": "my-routing-key", + "mandatoryRoute": false, + "persistentMessages": true, + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/streaming/kafka.mdx b/src/pages/docs/platform/integrations/streaming/kafka.mdx index 7b9d9f9011..e1619e59e1 100644 --- a/src/pages/docs/platform/integrations/streaming/kafka.mdx +++ b/src/pages/docs/platform/integrations/streaming/kafka.mdx @@ -15,7 +15,10 @@ If you want to send data from Kafka to Ably, you can use the [Ably Kafka Connect ## Create a Kafka integration -To create a Kafka integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create a Kafka integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with Kafka. 2. Click the **Integrations** tab. @@ -25,7 +28,44 @@ To create a Kafka integration in your [dashboard:](https://ably.com/dashboard/an 6. Configure the Kafka [settings](#settings). 7. Click **Create**. -You can also create a Kafka integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a Kafka rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "kafka", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "routingKey": "my-topic:#{message.name}", + "brokers": ["kafka.example.com:9092"], + "auth": { + "sasl": { + "mechanism": "scram-sha-256", + "username": "my-username", + "password": "my-password" + } + }, + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/streaming/kinesis.mdx b/src/pages/docs/platform/integrations/streaming/kinesis.mdx index 9f5e76de65..85f1bb168c 100644 --- a/src/pages/docs/platform/integrations/streaming/kinesis.mdx +++ b/src/pages/docs/platform/integrations/streaming/kinesis.mdx @@ -11,7 +11,10 @@ redirect_from: ## Create a Kinesis integration -To create a Kinesis integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create a Kinesis integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with Kinesis. 2. Click the **Integrations** tab. @@ -21,7 +24,42 @@ To create a Kinesis integration in your [dashboard:](https://ably.com/dashboard/ 6. Configure the Kinesis [settings](#settings). 7. Click **Create**. -You can also create a Kinesis integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a Kinesis rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "aws/kinesis", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "region": "us-west-1", + "streamName": "my-stream", + "partitionKey": "#{message.name}", + "format": "json", + "authentication": { + "authenticationMode": "assumeRole", + "assumeRoleArn": "arn:aws:iam::123456789012:role/my-ably-role" + }, + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/streaming/pulsar.mdx b/src/pages/docs/platform/integrations/streaming/pulsar.mdx index 9a1c4f1c84..abef28f2de 100644 --- a/src/pages/docs/platform/integrations/streaming/pulsar.mdx +++ b/src/pages/docs/platform/integrations/streaming/pulsar.mdx @@ -15,7 +15,10 @@ This feature is only available to [enterprise](/docs/platform/pricing/enterprise ## Create a Pulsar integration -To create a rule in your [dashboard:](https://ably.com/dashboard/any) + + + +To create a Pulsar integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with Pulsar. 2. Click the **Integrations** tab. @@ -25,7 +28,41 @@ To create a rule in your [dashboard:](https://ably.com/dashboard/any) 6. Configure the Pulsar [settings](#settings). 7. Click **Create**. -You can also create a Pulsar integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a Pulsar rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "pulsar", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "topic": "persistent://my-tenant/my-namespace/my-topic", + "serviceUrl": "pulsar+ssl://pulsar.example.com:6651", + "authentication": { + "authenticationMode": "token", + "token": "your-jwt-token" + }, + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + #### Settings diff --git a/src/pages/docs/platform/integrations/streaming/sqs.mdx b/src/pages/docs/platform/integrations/streaming/sqs.mdx index d742ebe3d9..827c9c1484 100644 --- a/src/pages/docs/platform/integrations/streaming/sqs.mdx +++ b/src/pages/docs/platform/integrations/streaming/sqs.mdx @@ -11,7 +11,10 @@ redirect_from: ## Create an SQS integration -To create an SQS integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create an SQS integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with SQS. 2. Click the **Integrations** tab. @@ -21,7 +24,42 @@ To create an SQS integration in your [dashboard:](https://ably.com/dashboard/any 6. Configure the SQS [settings](#settings). 7. Click **Create**. -You can also create an SQS integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create an SQS rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "aws/sqs", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "region": "us-west-1", + "awsAccountId": "123456789012", + "queueName": "my-queue", + "format": "json", + "authentication": { + "authenticationMode": "assumeRole", + "assumeRoleArn": "arn:aws:iam::123456789012:role/my-ably-role" + }, + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + #### Settings diff --git a/src/pages/docs/platform/integrations/webhooks/azure.mdx b/src/pages/docs/platform/integrations/webhooks/azure.mdx index 913e2ee7ec..719a39d631 100644 --- a/src/pages/docs/platform/integrations/webhooks/azure.mdx +++ b/src/pages/docs/platform/integrations/webhooks/azure.mdx @@ -12,7 +12,10 @@ redirect_from: ## Create an Azure Function integration -To create an Azure Function integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create an Azure Function integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with an Azure Function. 2. Click the **Integrations** tab. @@ -22,7 +25,37 @@ To create an Azure Function integration in your [dashboard:](https://ably.com/da 6. Configure the Azure Functions [settings](#settings). 7. Click **Create**. -You can also create an Azure Function integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create an Azure Function rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "http/azure-function", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "azureAppId": "my-azure-app-id", + "azureFunctionName": "my-function", + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/webhooks/cloudflare.mdx b/src/pages/docs/platform/integrations/webhooks/cloudflare.mdx index e5fca010d1..93c0e75320 100644 --- a/src/pages/docs/platform/integrations/webhooks/cloudflare.mdx +++ b/src/pages/docs/platform/integrations/webhooks/cloudflare.mdx @@ -12,7 +12,10 @@ redirect_from: ## Create a Cloudflare Worker integration -To create a Cloudflare Worker integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create a Cloudflare Worker integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with a Cloudflare Worker. 2. Click the **Integrations** tab. @@ -22,7 +25,37 @@ To create a Cloudflare Worker integration in your [dashboard:](https://ably.com/ 6. Configure the Cloudflare Worker [settings](#settings). 7. Click **Create**. -You can also create a Cloudflare Worker integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a Cloudflare Worker rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "http/cloudflare-worker", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "url": "https://my-worker.my-subdomain.workers.dev", + "headers": [ + { "name": "X-Custom-Header", "value": "my-value" } + ] + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/webhooks/gcp-function.mdx b/src/pages/docs/platform/integrations/webhooks/gcp-function.mdx index 59573cfc80..e1f18f6591 100644 --- a/src/pages/docs/platform/integrations/webhooks/gcp-function.mdx +++ b/src/pages/docs/platform/integrations/webhooks/gcp-function.mdx @@ -12,7 +12,10 @@ redirect_from: ## Create a Google Function integration -To create a Google Function integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create a Google Function integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with a Google Function. 2. Click the **Integrations** tab. @@ -22,7 +25,38 @@ To create a Google Function integration in your [dashboard:](https://ably.com/da 6. Configure the Google Function [settings](#settings). 7. Click **Create**. -You can also create a Google Function integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a Google Function rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "http/google-cloud-function", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "region": "us-west1", + "projectId": "my-gcp-project", + "functionName": "my-function", + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/webhooks/generic.mdx b/src/pages/docs/platform/integrations/webhooks/generic.mdx index cb43463072..e477b6cfa6 100644 --- a/src/pages/docs/platform/integrations/webhooks/generic.mdx +++ b/src/pages/docs/platform/integrations/webhooks/generic.mdx @@ -7,7 +7,10 @@ redirect_from: Generic HTTP webhooks enable you to trigger HTTP endpoints and notify external services when events occur in Ably. Events include when messages are published, presence events occur, changes in channel occupancy, and when channels are created or discarded. Data can be delivered individually or in batches to any HTTP endpoint. -## Create a generic HTTP webhook integration +## Create a generic HTTP webhook integration + + + To create a generic HTTP webhook integration in your [dashboard](https://ably.com/dashboard/any): @@ -15,11 +18,59 @@ To create a generic HTTP webhook integration in your [dashboard](https://ably.co 2. Click the **Integrations** tab. 3. Click the **New Integration Rule** button. 4. Choose **Webhook**. -4. Choose **Webhook** (again). +5. Choose **Webhook** (again). 6. Configure the webhook [settings](#settings). 7. Click **Create**. -You can also create a generic HTTP webhook integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a generic HTTP webhook rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "http", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "url": "https://example.com/webhook", + "headers": [ + { "name": "X-Custom-Header", "value": "my-value" } + ], + "format": "json", + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + + +Use the [Ably CLI](/docs/platform/tools/cli) to create a generic HTTP webhook rule: + + +```shell +ably integrations create \ + --rule-type http \ + --source-type channel.message \ + --target-url https://example.com/webhook +``` + + +Run `ably integrations create --help` for a full list of available options. + + + ## Settings diff --git a/src/pages/docs/platform/integrations/webhooks/ifttt.mdx b/src/pages/docs/platform/integrations/webhooks/ifttt.mdx index eb4847a547..7257ecbcab 100644 --- a/src/pages/docs/platform/integrations/webhooks/ifttt.mdx +++ b/src/pages/docs/platform/integrations/webhooks/ifttt.mdx @@ -12,7 +12,10 @@ redirect_from: ## Create a IFTTT integration -To create an IFTTT integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create an IFTTT integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with IFTTT. 2. Click the **Integrations** tab. @@ -22,7 +25,35 @@ To create an IFTTT integration in your [dashboard:](https://ably.com/dashboard/a 6. Configure the IFTTT [settings](#settings). 7. Click **Create**. -You can also create an IFTTT integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create an IFTTT rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "http/ifttt", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "webhookKey": "your-ifttt-webhook-key", + "eventName": "your-event-name" + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/webhooks/lambda.mdx b/src/pages/docs/platform/integrations/webhooks/lambda.mdx index b4ad7cac1a..1e614d7ec6 100644 --- a/src/pages/docs/platform/integrations/webhooks/lambda.mdx +++ b/src/pages/docs/platform/integrations/webhooks/lambda.mdx @@ -12,7 +12,10 @@ redirect_from: ## Create an AWS Lambda integration -To create an AWS Lambda integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create an AWS Lambda integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with AWS Lambda. 2. Click the **Integrations** tab. @@ -22,7 +25,40 @@ To create an AWS Lambda integration in your [dashboard:](https://ably.com/dashbo 6. Configure the AWS Lambda [settings](#settings). 7. Click **Create**. -You can also create an AWS Lambda integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create an AWS Lambda rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "aws/lambda", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "region": "us-west-1", + "functionName": "my-function", + "authentication": { + "authenticationMode": "assumeRole", + "assumeRoleArn": "arn:aws:iam::123456789012:role/my-ably-role" + }, + "enveloped": true + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings diff --git a/src/pages/docs/platform/integrations/webhooks/zapier.mdx b/src/pages/docs/platform/integrations/webhooks/zapier.mdx index bed3b42ed9..4d499b5483 100644 --- a/src/pages/docs/platform/integrations/webhooks/zapier.mdx +++ b/src/pages/docs/platform/integrations/webhooks/zapier.mdx @@ -13,7 +13,10 @@ redirect_from: ## Create a Zapier integration -To create a Zapier integration in your [dashboard:](https://ably.com/dashboard/any) + + + +To create a Zapier integration in your [dashboard](https://ably.com/dashboard/any): 1. Login and select the application you wish to integrate with Zapier. 2. Click the **Integrations** tab. @@ -23,7 +26,34 @@ To create a Zapier integration in your [dashboard:](https://ably.com/dashboard/a 6. Configure the Zapier [settings](#settings). 7. Click **Create**. -You can also create a Zapier integration using the [Control API](/docs/platform/account/control-api). + + + +Use the [Control API](/docs/platform/account/control-api) to create a Zapier rule by sending a `POST` request to `/apps/{app_id}/rules`: + + +```shell +curl -X POST https://control.ably.net/v1/apps/{APP_ID}/rules \ + -H "Authorization: Bearer {ACCESS_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "ruleType": "http/zapier", + "requestMode": "single", + "source": { + "channelFilter": "", + "type": "channel.message" + }, + "target": { + "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/" + } + }' +``` + + +Refer to the [Control API reference](/docs/api/control-api) for a full list of available parameters. + + + ### Settings