v4

OpenAPI 3.0.0MIT2026-07-311494532.1 MB

Integrations

Generate chat OAuth URL

Deprecated — use POST /integrations/channel-connections/oauth (connect) or POST /integrations/channel-endpoints/oauth (link_user) instead. Generate an OAuth URL for chat integrations like Slack, MS Teams, and Webex. This URL allows subscribers to authorize the integration, enabling the system to send messages through their chat workspace. The generated URL expires after 5 minutes.

post/v1/integrations/chat/oauth

Headers

idempotency-keystring

A header for idempotency purposes

Request body

subscriberIdstring

The subscriber ID to link the channel connection to. For Slack: Required for incoming webhook endpoints, optional for workspace connections. For MS Teams: Optional. Admin consent is tenant-wide and can be associated with a subscriber for organizational purposes.

integrationIdentifierstring required

Integration identifier

connectionIdentifierstring

Identifier of the channel connection that will be created. It is generated automatically if not provided.

contextobject

scopestring[]

Slack only: OAuth scopes to request during authorization. These define the permissions your Slack integration will have. If not specified, default scopes will be used: chat:write, chat:write.public, channels:read, groups:read, users:read, users:read.email. Webex: OAuth scopes to request during authorization. Defaults to: spark:messages_write, spark:rooms_read, spark:people_read, spark:memberships_read, spark:kms. MS Teams: This parameter is ignored. MS Teams uses admin consent with pre-configured permissions in Azure AD. Note: The generated OAuth URL expires after 5 minutes.

userScopestring[]

Slack only, link_user mode: User-level OAuth scopes to request during authorization. Used when mode is "link_user" to identify the Slack user via "Sign in with Slack". If not specified, defaults to: identity.basic.

mode'connect' | 'link_user'

OAuth flow mode. Use "connect" (default) to create a workspace channel connection, or "link_user" to identify the subscriber's Slack user ID without creating a connection.

connectionMode'subscriber' | 'shared'

Connection mode that determines how the channel connection is scoped. Use "subscriber" (default) to associate the connection with a specific subscriber. Use "shared" to associate the connection with a context instead of a subscriber — subscriberId will not be stored on the connection.

autoLinkUserboolean

When true, after the workspace/tenant connection is created the OAuth flow also links the subscriber who clicked "Connect" as a personal endpoint. For Slack, this uses the authed_user.id already returned by oauth.v2.access — no extra redirect. For Webex, this uses the authenticated Webex person returned by people/me — no extra redirect. For MS Teams, this triggers a second OAuth redirect for delegated user-identity consent. Defaults to false when omitted; the SlackConnectButton and MsTeamsConnectButton SDK components default this to true.

Example request

{
  "subscriberId": "subscriber-123",
  "connectionIdentifier": "slack-connection-abc123",
  "scope": [
    "chat:write",
    "chat:write.public",
    "channels:read",
    "groups:read",
    "users:read",
    "users:read.email",
    "incoming-webhook"
  ],
  "userScope": [
    "identity.basic"
  ],
  "mode": "link_user",
  "connectionMode": "shared",
  "autoLinkUser": true
}

Response

Created

urlstring required

The OAuth authorization URL for the chat provider. For Slack: https://slack.com/oauth/v2/authorize?... For MS Teams: https://login.microsoftonline.com/.../adminconsent?... This URL should be presented to the user to authorize the integration. Expires after 5 minutes.

Example response

{
  "url": "https://slack.com/oauth/v2/authorize?state=..."
}