docs: rewrite Actor-to-Actor integration page by marcel-rbro · Pull Request #2546 · apify/apify-docs

marcel-rbro · 2026-05-19T11:36:01Z

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  markers for items still pending confirmation

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

apify-service-account · 2026-05-19T11:36:42Z

✅ Preview for this PR (commit 5d5f737) is ready at https://pr-2546.preview.docs.apify.com (see action run).

Refresh the Add an integration flow to match the new integrations dialog in Apify Console. The previous instructions referenced a removed "Apify (Connect Actor or Task)" affordance. Several TODOs remain inline for items that still need confirmation. Refs #2460 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apify-service-account · 2026-05-19T11:41:41Z

Python client model regeneration failed. See workflow run.

- Use "trigger" instead of "fire" for consistency with platform terminology - Drop conversational "still" from the test-run note - Remove emphasis bold from "source" Actor (style guide reserves bold for UI elements) - Replace single "Blog tutorial" link with a "Next steps" section pointing at the two sibling pages plus the blog walkthrough Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

- Rename page title to "Develop integration-ready Actors" so the developer audience is explicit; add sidebar_label to match - Lead the page with a one-line audience statement and an explicit framing that any Actor can be a target but designed ones provide a better experience - Add a note linking to Integration Actors in Apify Store for inspiration, using the UI term "Integration Actor" for the catalog/category and "integration-ready" only as a descriptive adjective for Actor design - Update the cross-link in the Actor-to-Actor page to match the new sibling title Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

In index.md: - Replace ambiguous pronoun "It" with explicit "The UI" on the Implementation details paragraph In integration_ready_actors.md: - Remove bold used for emphasis (dataset ID, dataset contents, "only") - bold reserved for UI elements per style guide - Drop softening "ideally try to" from the complexity-hiding rule - Replace first-person plural ("we", "we'd", "we're") with imperative/second-person voice throughout the Example section - Fix "fit to memory" -> "fit in memory" - Clean up field labels (ID instead of Id, "table or collection" instead of "table / collection") - Refresh the publishing flow to reference the new "Add integration" dialog instead of the removed "Connect Actor or task" button - Fix malformed mailto link (Actor%specific -> Actor%20specific) - Add inline TODO markers for the stale contact-support listing workflow and the outdated specific_vs_generic_integrations.png screenshot, mirroring the TODO convention from index.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

TC-MO · 2026-05-21T09:48:53Z

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

+<!-- TODO: confirm the YouTube video (zExnYbvFoBM) still reflects the current flow; replace or remove if outdated. -->


that is a terrible spell check :D, also I highly doubt I highly doubt that the video is still relevant. I would nuke it, if by some chance it is okay I still would demote it from full on embed to just link. And definitely place it differently so it isn't before the prose that has highest chance ATM to not e stale

TC-MO

Some changes requested, some related to updated content, some cleanup opportunities.

TC-MO · 2026-05-21T10:54:25Z

+1. Click the Actor card to open its setup screen. <!-- TODO: confirm the post-selection screen still uses the trigger + payload + variables layout described below. Recapture screenshots if the UI differs. -->

-This leads you to a setup screen, where you can provide:
+<!-- TODO: add a screenshot of the new Add integration dialog. -->


If we ship with screenshots we'll be doing double duty later when remaking them into figma artifacts, but this page has already surfaced few times so lets ship it with screenshot and change to svgs later

TC-MO · 2026-05-21T10:56:34Z

+- `datasetId: string` - ID of the dataset to upload
+- `connectionString: string` - credentials for the database connection
+- `tableName: string` - name of the table or collection



here you have lowercase, L67-68 uppercase. Lets pick one and be consistent

TC-MO · 2026-05-21T10:57:36Z

+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


no need to use symbol when a simple word does the same job

Suggested change

- `tableName: string` - Name of table / collection

- `tableName: string` - Name of table or collection

TC-MO · 2026-05-21T10:58:43Z


 ## Example

 To illustrate the above, here is a simplified example of an Actor that uploads a dataset to a table/collection in some database.


Suggested change

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.

TC-MO · 2026-05-21T11:01:05Z

+    ![Integration trigger select](./images/integration_triggers.png)
+
+- **Input for the integrated Actor** - 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.
+- **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, so `{{resource.defaultDatasetId}}` or `{{resource.defaultKeyValueStoreId}}` is usually all you need.


Usually just feels wrong, it implies some unusual cases that should be enumerated, but are not.

Suggested change

- **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, so `{{resource.defaultDatasetId}}` or `{{resource.defaultKeyValueStoreId}}` is usually all you need.

- **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.

TC-MO · 2026-05-21T11:02:50Z

@@ -1,6 +1,6 @@
 ---
 title: What are Actor integrations?


Why ask when we are explaining.

Suggested change

title: What are Actor integrations?

title: What are Actor integrations

TC-MO · 2026-05-21T11:03:50Z

-![Add integration](./images/integrations_add.png)
-3. Find the Actor or task you want to integrate with and click `Connect`.
+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.


Wouldn't it be better if instead of nestd bullet that would be a regular prose below the list?

marcel-rbro force-pushed the docs/actor-to-actor-rewrite branch from d0d9d70 to 779baca Compare May 19, 2026 11:38

marcel-rbro changed the base branch from docs/integrations-restructure-tiers to master May 19, 2026 11:38

github-actions Bot assigned marcel-rbro May 19, 2026

github-actions Bot added the t-docs Issues owned by technical writing team. label May 19, 2026

marcel-rbro and others added 2 commits May 19, 2026 15:02

marcel-rbro marked this pull request as ready for review May 21, 2026 09:09

marcel-rbro requested review from TC-MO and Copilot and removed request for Copilot May 21, 2026 09:09

Copilot started reviewing on behalf of marcel-rbro May 21, 2026 09:10 View session

TC-MO reviewed May 21, 2026

View reviewed changes

TC-MO requested changes May 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

docs: rewrite Actor-to-Actor integration page#2546
marcel-rbro wants to merge 4 commits into
masterfrom
docs/actor-to-actor-rewrite

marcel-rbro commented May 19, 2026

Uh oh!

apify-service-account commented May 19, 2026 •

edited

Loading

Uh oh!

apify-service-account commented May 19, 2026

Uh oh!

TC-MO May 21, 2026 •

edited

Loading

Uh oh!

TC-MO left a comment

Uh oh!

TC-MO May 21, 2026

Uh oh!

TC-MO May 21, 2026

Uh oh!

TC-MO May 21, 2026

Uh oh!

TC-MO May 21, 2026

Uh oh!

TC-MO May 21, 2026

Uh oh!

TC-MO May 21, 2026

Uh oh!

TC-MO May 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- `tableName: string` - Name of table / collection
	- `tableName: string` - Name of table or collection


		## Example

		To illustrate the above, here is a simplified example of an Actor that uploads a dataset to a table/collection in some database.

	- 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, so `{{resource.defaultDatasetId}}` or `{{resource.defaultKeyValueStoreId}}` is usually all you need.
	- 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.

	title: What are Actor integrations?
	title: What are Actor integrations

Conversation

marcel-rbro commented May 19, 2026

Summary

Outstanding TODOs (to resolve before marking ready)

Test plan

Uh oh!

apify-service-account commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apify-service-account commented May 19, 2026

Uh oh!

TC-MO May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TC-MO left a comment

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

apify-service-account commented May 19, 2026 •

edited

Loading

TC-MO May 21, 2026 •

edited

Loading