docs: rewrite Actor-to-Actor integration page (#2546)

## Summary
- Rewrite the **Add an integration** flow in `index.md` to match the new
integrations dialog in Apify Console; the previous instructions
referenced a removed *Apify (Connect Actor or Task)* affordance
- Minor tone and style cleanup (active voice, bold for UI elements,
removed sales phrasing)
- Inline `<!-- TODO -->` markers for items still pending confirmation

Refs #2460

This PR is stacked on top of #2506
(`docs/integrations-restructure-tiers`). Once that lands, rebase the
base to `master`.

## Outstanding TODOs (to resolve before marking ready)
- [ ] Confirm YouTube embed (`zExnYbvFoBM`) still reflects the current
flow
- [ ] Confirm how Actors get listed under **Suggested for this Actor**
- [ ] Confirm the post-selection screen still uses the trigger + payload
+ variables layout; recapture screenshots if not
- [ ] Capture a new screenshot for the **Add integration** dialog
(placeholder TODO in source)
- [ ] Confirm "compute units" is still the right billing-unit name in
the test-run note
- [ ] Confirm the linked blog tutorial is still current
- [ ] Second pass on `integration-ready-actors.md` (specific vs generic
distinction) and `integrating-actors-via-api.md`

## Test plan
- [ ] `pnpm lint` passes
- [ ] `pnpm build` produces no broken-link errors for
`/integrations/actors`
- [ ] Visual check of the rendered page in dev server

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: marcel-rbro

sources/platform/integrations/actors/images/integration_setup_screen.png

@@ -1,6 +1,6 @@
 ---
-title: What are Actor integrations?
-description: Learn how to connect Actors together and trigger tasks from other Actors, enabling you to build automated multi-step workflows on the Apify platform.
+title: Actor-to-Actor integrations
+description: Learn how to connect Actors and tasks on the Apify platform using the integrations catalog in Apify Console to build automated multi-step workflows.
 sidebar_label: Actor-to-Actor
 sidebar_position: 0
 slug: /integrations/actors
@@ -12,44 +12,49 @@ You can check out a catalog of Integration Actors within [Apify Store](https://a
 
 :::
 
-Actor integrations provide a way to connect your Actors with other Actors or tasks easily. They provide a new level of flexibility, as adding a new integration simply means creating [integration-ready Actors](/platform/integrations/actors/integration-ready-actors). Thus, new integrations can be created by the community itself.
+Actor-to-Actor integrations connect your Actors with other Actors or tasks, letting you build multi-step workflows on the Apify platform. Because any [integration-ready Actor](/platform/integrations/actors/integration-ready-actors) can act as the target of an integration, the community can keep extending the catalog with new integrations.
 
-<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/zExnYbvFoBM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+## Add an integration
 
-## How to integrate an Actor with other Actors?
+To connect an Actor with another Actor or task:
 
-To integrate one Actor with another:
+1. Open the Actor's detail page and select the **Integrations** tab.
+    - If the Actor already has integrations set up, the **Integrations** tab lists them instead. Click **Add integration** to open the catalog.
+1. In the **Add integration** catalog, find the target Actor in one of two places:
+    - **Suggested for this Actor** - Actors relevant to the source Actor's output. <!-- TODO: confirm how an Actor ends up in this list (Store category, manual curation, similarity, or a combination). -->
+    - **Search integrations** field at the top - search across the full catalog.
+1. Click the Actor card to open its setup screen.
 
-1. Navigate to the **Integrations** tab in the Actor's detail page.
-2. Select `Apify (Connect Actor or Task)`.
-![Add integration](./images/integrations_add.png)
-3. Find the Actor or task you want to integrate with and click `Connect`.
+On the setup screen, configure:
 
-This leads you to a setup screen, where you can provide:
+- **Start when** - Events that trigger the integrated Actor. These match webhook [event types](/platform/integrations/webhooks/events) (`run succeeded`, `build failed`, and so on).
+- **Actor input** - The input usually has two parts: static fields whose value doesn't change between runs (for example, a database connection string or table name) and dynamic fields specific to the triggering run (for example, a dataset ID). Static fields go in as-is. Dynamic fields are pulled from the implicit `payload` field (the default for most integration-ready Actors) or set with variables. The **Available variables** button in the input panel lists the variables you can interpolate.
+- **Available variables** - The same variables as in webhooks. The most common is `{{resource}}`, which holds the Run object in the shape returned by the [API](/api/v2/actor-run-get), or the Build object for build event types. Variables support dot notation, `{{resource.defaultDatasetId}}` and `{{resource.defaultKeyValueStoreId}}` cover most cases.
 
-- **Triggers**: Events that will trigger the integrated Actor. These are the same as webhook [event types](/platform/integrations/webhooks/events) (*run succeeded*, *build failed*, etc.)
-
-![Integration trigger select](./images/integration_triggers.png)
-
-- **Input for the integrated Actor**: Typically, the input has two parts. The information that is independent of the run triggering it and information that is specific for that run. The "independent" information (e.g. connection string to database or table name) can be added to the input as is. The information specific to the run (e.g. dataset ID) is either obtained from the implicit `payload` field (this is the case for most Actors that are integration-ready), or they can be provided using variables.
-- **Available variables** are the same ones as in webhooks. The one that you probably are going to need the most is `{{resource}}`, which is the Run object in the same shape you get from the [API](/api/v2/actor-run-get) (for build event types, it will be the Build object). The variables can make use of dot notation, so you will most likely just need `{{resource.defaultDatasetId}}` or `{{resource.defaultKeyValueStoreId}}`.
+<img src={require("./images/integration_setup_screen.png").default} alt="Integration setup screen" width="60%" />
 
 ## Test your integration
 
-When adding a new integration, you can test it using a past run or build as a trigger. This will trigger a run of your target Actor or task as if your desired trigger event just occurred. The only difference between a test run and regular run is that the trigger's event type will be set to 'TEST'. The test run will still consume compute units.
+When you add a new integration, you can test it using a past run or build as a trigger. The integrated Actor or task runs as if the trigger event just happened. The only difference from a regular run is that the event type is set to `TEST`. Test runs consume compute units.
+
+To test, set the input and options, save, then pick an option from the test menu:
 
-To test your integration, first set your desired input and options and save. You can then select one of the options from the menu. If the source of your integration is a task, you can test it using a past run. For Actors, you can use a past run or build. Alternatively, if the source of your integration has neither, you can test your integration with a random joke in the webhook's payload.
+- A past run, if the source is an Actor or a task.
+- A past build, if the source is an Actor.
+- A random joke in the webhook payload, if the source has no runs or builds yet.
 
 ![Test integration options](./images/integrations_test_options.png)
 
-When testing with a custom run or build, you will need to enter its ID. You can find it on the run's or build's detail page. Ensure that the run or build belongs to the **source** Actor, since that is where the trigger will be coming from.
+For a custom run or build, enter its ID - you can find it on the run's or build's detail page. The run or build must belong to the source Actor, since that is where the trigger originates.
 
 ## Implementation details
 
-Under the hood, the Actor integrations use regular [HTTP POST webhooks](https://www.redhat.com/en/topics/automation/what-is-a-webhook) and target the Apify API, for which this feature provides a friendlier UI. The UI allows you to fill the payload template using the Actor input UI rather than plain text and constructs the URL to start your Actor with the given options.
+Actor integrations are regular [HTTP POST webhooks](https://www.redhat.com/en/topics/automation/what-is-a-webhook) targeting the Apify API. The Integrations UI is a friendlier wrapper that lets you fill the payload template through the Actor input UI instead of plain text, and constructs the URL that starts the target Actor with the chosen options.
 
-The UI ensures that the variables are enclosed in strings, meaning that even the payload template is a valid JSON, not just the resulting interpolation. It also automatically adds the `payload` field that contains the default webhook payload. Thanks to this, when using Actors that are meant to be used as integrations, users don't have to fill in the variables: the Actor takes the data from this field by itself.
+The UI keeps variables enclosed in strings, which means the payload template is valid JSON rather than only the interpolated result. The UI also adds a `payload` field with the default webhook payload, so integration-ready Actors can read run data from `payload` without users having to set variables themselves.
 
-## Blog tutorial
+## Next steps
 
-You can read a complete example of integrating two Actors in [this tutorial](https://blog.apify.com/connecting-scrapers-apify-integration/).
+- [Develop integration-ready Actors](/platform/integrations/actors/integration-ready-actors) - design your own Actor to be used as an integration target.
+- [Integrating Actors via API](/platform/integrations/actors/integrating-actors-via-api) - set up the same integrations programmatically with the Apify API.
+- [Connecting scrapers with Apify integrations](https://blog.apify.com/connecting-scrapers-apify-integration/) - a complete walkthrough on the Apify blog.

sources/platform/integrations/actors/index.md

@@ -1,5 +1,5 @@
 ---
-title: Integrating Actors via API
+title: Integrate Actors via API
 description: Use the Apify API to integrate Actors and tasks together using webhooks. Configure the required fields to display integrations in Apify Console.
 sidebar_position: 2
 slug: /integrations/actors/integrating-actors-via-api

sources/platform/integrations/actors/integrating_actors_via_api.md

@@ -1,29 +1,38 @@
 ---
-title: Creating integration Actors
-description: Build Actors designed to work as integrations with other Actors and tasks. Handle dynamic input, payload fields, and large datasets efficiently.
+title: Develop integration-ready Actors
+description: Learn how to develop Actors that work cleanly as integration targets, including input design, payload handling, and dataset processing patterns.
+sidebar_label: Develop integration-ready Actors
 sidebar_position: 1
 slug: /integrations/actors/integration-ready-actors
 ---
 
-Any Actor can be used in integrations. In order to provide a smooth experience for its users, there are few things to keep in mind.
+This page is for Actor developers. It covers the patterns to follow when building an Actor that other users will connect as an integration target - input shape, handling the implicit `payload` field, and processing dataset references rather than dataset contents.
+
+:::note Integration Actors
+
+For inspiration, browse [Integration Actors in Apify Store](https://apify.com/store/categories/integrations) - published Actors designed to be used as integration targets.
+
+:::
+
+Any Actor can be used as an integration target, but Actors designed for the role give users a smoother experience. The rest of this page assumes you are developing such an Actor.
 
 ## General guidelines
 
 If your Actor is supposed to be used as an integration, it will most likely have an input that can be described as two groups of fields. The first group is the "static" part of the input - the fields that have the same value whenever the integration is triggered. The second, "dynamic", group are fields that are specific to the triggering event - information from the run or build that triggered the integration.
 
-The Actor should ideally try to hide its complexity from users and take all the "dynamic" fields from the implicit `payload` field - it is attached automatically. This way, users don't have to take care of passing in variables on their own and only need to take care of the static part of the input.
+The Actor should hide its complexity from users and take all the "dynamic" fields from the implicit `payload` field - it is attached automatically. This way, users don't have to take care of passing in variables on their own and only need to take care of the static part of the input.
 
-An important thing to remember is that only the **dataset ID** is passed to the Actor as input, not the **dataset contents**. This means that the Actor needs to take care of getting the actual contents of the dataset. And, ideally, it should not load the full dataset while doing so, as it might be too large to fit to memory, but rather process it in batches.
+Only the dataset ID is passed to the Actor as input, not the dataset contents. The Actor needs to fetch the contents of the dataset itself. Ideally, it should not load the full dataset at once, as it might be too large to fit in memory, but rather process it in batches.
 
 ## Example
 
-To illustrate the above, here is a simplified example of an Actor that uploads a dataset to a table/collection in some database.
+To illustrate the above, here is a simplified example of an Actor that uploads a dataset to a database table or collection.
 
-We would start with an input that looks something like this:
+Start with an input that looks something like this:
 
-- `datasetId: string` - Id of dataset that should be uploaded
+- `datasetId: string` - ID of the dataset to upload
 - `connectionString: string` - Credentials for the database connection
-- `tableName: string` - Name of table / collection
+- `tableName: string` - Name of the table or collection
 
 With this input schema, users have to provide an input that looks like this:
 
@@ -35,13 +44,13 @@ With this input schema, users have to provide an input that looks like this:
 }
 ```
 
-And in the Actor code, we'd use this to get the values:
+In the Actor code, use this to get the values:
 
 ```js
 const { datasetId, connectionString, tableName } = await Actor.getInput();
 ```
 
-To make the integration process smoother, it's possible to define an input that's going to be prefilled when your Actor is being used as an integration. You can do that in the Actor's **Settings** tab, on the **Integrations** form. In this example, we'd use:
+To make the integration process smoother, define an input that's prefilled when your Actor is used as an integration. Set this on the Actor's **Settings** tab, in the **Integrations** form. For this example, use:
 
 ```json
 {
@@ -53,10 +62,10 @@ This means that users will see that the `defaultDatasetId` of the triggering run
 
 Explicitly stating what is the expected input when Actor is being used as an integration is a preferred way.
 
-However, if the Actor is **only** supposed to be used as integration, we can use a different input schema:
+However, if the Actor is only supposed to be used as an integration, use a different input schema:
 
 - `connectionString: string` - Credentials for the database connection
-- `tableName: string` - Name of table / collection
+- `tableName: string` - Name of the table or collection
 
 In this case, users only need to provide the "static" part of the input:
 
@@ -74,21 +83,22 @@ const { payload, connectionString, tableName } = await Actor.getInput();
 const datasetId = payload.resource.defaultDatasetId;
 ```
 
-It's also possible to combine both approaches, which is useful for development purposes or advanced usage. It would mean keeping the `datasetId` in the input, only hidden under an "Advanced options" section, and using it like this:
+You can also combine both approaches, which is useful for development or advanced usage. Keep the `datasetId` in the input, hidden under an "Advanced options" section, and use it like this:
 
 ```js
 const { payload, datasetId } = await Actor.getInput();
 const datasetIdToProcess = datasetId || payload?.resource?.defaultDatasetId;
 ```
 
-In the above example, we're focusing on accessing a run's default dataset, but the approach would be similar for any other field.
+The example above focuses on accessing a run's default dataset, but the approach is similar for any other field.
 
 ## Make your Actor available to other users
 
-To allow other users to use your Actor as an integration, all you need to do is [publish it in Apify Store](/platform/actors/publishing), so users can then integrate it using the **Connect Actor or task** button on the **Integrations** tab of any Actor. While publishing the Actor is enough, there are two ways to make it more visible to users.
+To allow other users to use your Actor as an integration, [publish it in Apify Store](/platform/actors/publishing). Users can then find it in the **Add integration** dialog on the **Integrations** tab of any Actor. While publishing is enough, there are two ways to make your Actor more visible to users.
 
-For Actors that are generic enough to be used with most other Actors, it's possible to have them listed under **Generic integrations** in the **Integrations** tab. This includes (but is not limited to) Actors that upload datasets to databases, send notifications through various messaging systems, create issues in ticketing systems, etc. To have your Actor listed under the generic integrations, [contact support](http://apify.com/contact).
+For Actors generic enough to be used with most other Actors, you can have them listed under **Generic integrations** in the **Add integration** dialog. This includes (but is not limited to) Actors that upload datasets to databases, send notifications through various messaging systems, or create issues in ticketing systems. To have your Actor listed under generic integrations, [contact support](mailto:support@apify.com?subject=Actor%20generic%20integration). <!-- TODO: confirm the contact-support workflow is still current; the new catalog UI may use a different listing mechanism. -->
 
-Some Actors can only be integrated with a few or even just one other Actor. Let's say that you have an Actor that's capable of scraping profiles from a social network. It makes sense to show it for Actors that produce usernames from the social network but not for Actors that produce lists of products. In this case, it's possible to have the Actor listed as **Specific to this Actor** under the Actor's **Integrations** tab. To have your Actor listed as specific to another Actor, [contact support](http://apify.com/contact).
+Some Actors can only be integrated with a few - or even just one - other Actor. For example, an Actor that scrapes profiles from a social network is relevant for Actors that produce usernames from that network, but not for Actors that produce product lists. In this case, you can have the Actor listed under **Suggested for this Actor** on the source Actor's **Integrations** tab. To have your Actor listed as specific to another Actor, [contact support](mailto:support@apify.com?subject=Actor%20specific%20integration). <!-- TODO: confirm the contact-support workflow and the exact UI section name ("Suggested for this Actor" vs "Specific to this Actor"). -->
 
+<!-- TODO: recapture or replace `specific_vs_generic_integrations.png` to match the new Add integration dialog. -->
 ![Specific vs generic integrations](./images/specific_vs_generic_integrations.png)