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	`slack_bot`
`integrationAlias`	Field used when targeting a configured alias after setup	`slack_bot`
`workspaceIntegrationId`	Exact UUID of the configured workspace integration	`7df5c03e-4df5-4b5f-95a7-5277d8f972db`
`integrationOrAlias`	MCP declaration helper path parameter only	`slack_bot` or `slack`

integrationName is not an integration ID. 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": "slack_bot",
  "displayName": "Support Slack Bot",
  "connectionStrategy": "fixed",
  "connectionId": "9b2b73f7-b575-42b1-9a8f-c233dff5127d"
}

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

json

{
  "integrationName": "slack",
  "integrationAlias": "slack_bot",
  "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 when there is one configured instance of that integration in the workspace.

If a workspace has multiple configured integrations with the same integrationName and you only pass integrationName, Weavz cannot safely infer which one you meant.

Repeated Integration Example

One workspace can configure Slack twice:

Configured instance	`integrationName`	`alias`	Strategy
Support bot	`slack`	`slack_bot`	`fixed`
End-user Slack	`slack`	`slack_user`	`per_user`

Use the bot alias for shared operational messages:

json

{
  "integrationName": "slack",
  "integrationAlias": "slack_bot",
  "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": "slack_user",
  "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
`slack_bot`	`send_channel_message`	`slack_bot__send_channel_message`
`slack_user`	`send_channel_message`	`slack_user__send_channel_message`

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

javascript

await weavz.slack_bot.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.