Integration Selectors

Understand integration names, workspace integration aliases, and exact workspace integration IDs.

Integration Selectors

Weavz separates catalog integrations from configured workspace integrations. This matters when a workspace uses the same integration more than once, such as a Slack bot account and a Slack user account.

Quick Reference

Term	Meaning	Example
`integrationName`	Catalog integration slug	`slack`, `github`, `storage`
Workspace integration	A configured instance of an integration inside a workspace	Slack configured as a bot account
`alias`	Field used when creating or updating a workspace integration; agents see this name	`office_slack`
`integrationAlias`	Field used when targeting the same configured alias after setup	`office_slack`
`workspaceIntegrationId`	Exact UUID of the configured workspace integration	`7df5c03e-4df5-4b5f-95a7-5277d8f972db`

integrationName is not an integration ID and agents should not use it as their primary selector. It is the base catalog slug. The configured workspace integration ID is workspaceIntegrationId.

Configure Once, Target Later

When adding an integration to a workspace, you assign the configured instance an alias:

json

{
  "integrationName": "slack",
  "alias": "office_slack",
  "displayName": "Office Slack",
  "connectionStrategy": "fixed",
  "connectionId": "9b2b73f7-b575-42b1-9a8f-c233dff5127d"
}

After that, execution surfaces target the configured instance with integrationAlias:

json

{
  "integrationName": "slack",
  "integrationAlias": "office_slack",
  "actionName": "send_channel_message",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "input": {
    "channel": "C0123456789",
    "text": "Support summary is ready."
  }
}

The same configured instance also has a UUID. Use workspaceIntegrationId when you have it:

json

{
  "integrationName": "slack",
  "workspaceIntegrationId": "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
  "actionName": "send_channel_message",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "input": {
    "channel": "C0123456789",
    "text": "Support summary is ready."
  }
}

Selector Specificity

Use selectors in this order:

workspaceIntegrationId when your backend has the configured integration UUID.
integrationAlias when you want a stable readable selector.
integrationName only for catalog discovery and APIs whose route is explicitly scoped to a catalog app slug.

If a workspace has multiple configured integrations with the same integrationName and you only pass integrationName to an execution surface, Weavz cannot safely infer which configured instance you meant. When a workspace integration is created without an explicit alias, Weavz defaults the alias to the catalog slug, so single-instance workspaces still get a stable alias such as slack.

Repeated Integration Example

One workspace can configure Slack twice:

Configured instance	`integrationName`	`alias`	Strategy
Office Slack	`slack`	`office_slack`	`fixed`
Customer Slack	`slack`	`customer_slack`	`per_user`

Use the office alias for shared operational messages:

json

{
  "integrationName": "slack",
  "integrationAlias": "office_slack",
  "actionName": "send_channel_message",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "input": {
    "channel": "C0123456789",
    "text": "A new ticket is waiting."
  }
}

Use the user alias and endUserId for per-user credentials:

json

{
  "integrationName": "slack",
  "integrationAlias": "customer_slack",
  "actionName": "send_channel_message",
  "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
  "endUserId": "user_123",
  "input": {
    "channel": "C0123456789",
    "text": "Sent from the connected user's Slack account."
  }
}

MCP Tool Aliases

MCP tools also store integrationAlias. When a server syncs from workspace integrations, the workspace integration alias becomes the MCP tool integrationAlias.

In Tool Mode, the alias becomes part of the tool name:

`integrationAlias`	`actionName`	Tool name
`office_slack`	`send_channel_message`	`office_slack__send_channel_message`
`customer_slack`	`send_channel_message`	`customer_slack__send_channel_message`

In Code Mode, the alias becomes the namespace under weavz:

javascript

await weavz.office_slack.send_channel_message({
  channel: 'C0123456789',
  text: 'Sent by the shared bot.',
})

Manual MCP tool aliases are server-local. Workspace integration aliases are workspace configuration and can sync into MCP servers.

The MCP declaration helper uses aliases:

text

GET /api/v1/mcp/servers/:id/declarations/:alias