asyncapi: 3.0.0 info: title: Slack Events API version: 1.0.0 description: >- The Slack Events API enables apps to respond to activities in Slack by subscribing to specific event types. Rather than polling for changes, apps receive HTTP POST payloads when subscribed events occur, such as new messages, reactions, channel changes, or user updates. The Events API offers two delivery options: a public HTTP endpoint that Slack sends event payloads to, or Socket Mode which uses WebSockets for apps that cannot expose a public URL. Events are categorized into Team Events (workspace-scoped, requiring corresponding OAuth scopes) and Bot Events (subscribed on behalf of the app's bot user). termsOfService: https://slack.com/terms-of-service/api contact: name: Slack Developer Support url: https://docs.slack.dev license: name: Slack API Terms of Service url: https://slack.com/terms-of-service/api externalDocs: description: Slack Events API documentation url: https://docs.slack.dev/apis/events-api servers: httpEndpoint: host: '{your-server}' pathname: /slack/events protocol: https description: >- Your app's Request URL that receives HTTP POST payloads from Slack when subscribed events occur. Must respond with HTTP 200 within 3 seconds. socketMode: host: wss-primary.slack.com protocol: wss description: >- Slack Socket Mode WebSocket connection for receiving events without exposing a public HTTP endpoint. Initiated via apps.connections.open Web API method. defaultContentType: application/json channels: eventCallback: address: /slack/events description: >- Primary channel for receiving all subscribed Slack events. Events are delivered as HTTP POST requests wrapped in an event callback envelope containing metadata about the event and the inner event payload. Your app must respond with HTTP 200 within 3 seconds. If not acknowledged, Slack retries up to 3 times with exponential backoff. messages: eventCallbackMessage: $ref: '#/components/messages/EventCallback' urlVerification: address: /slack/events description: >- Used during initial app configuration. When you first configure your Request URL, Slack sends a url_verification challenge event. Your app must respond with the challenge value to confirm ownership. messages: urlVerificationMessage: $ref: '#/components/messages/UrlVerification' operations: receiveEvent: action: receive channel: $ref: '#/channels/eventCallback' summary: Receive event callbacks from Slack description: >- Receives event callback payloads from Slack when subscribed events occur in the workspace. Each payload is wrapped in an event callback envelope containing metadata and the inner event object. messages: - $ref: '#/channels/eventCallback/messages/eventCallbackMessage' handleUrlVerification: action: receive channel: $ref: '#/channels/urlVerification' summary: Handle URL verification challenge description: >- Responds to URL verification challenges during initial Request URL configuration. The app must echo back the challenge value. messages: - $ref: '#/channels/urlVerification/messages/urlVerificationMessage' components: messages: EventCallback: name: Event Callback title: Slack Event Callback summary: An event callback payload from the Slack Events API description: >- The outer envelope for all event deliveries. Contains metadata about the event and the inner event object with the actual event data. contentType: application/json payload: $ref: '#/components/schemas/EventCallbackEnvelope' UrlVerification: name: URL Verification title: Slack URL Verification Challenge summary: URL verification challenge sent during Request URL configuration contentType: application/json payload: $ref: '#/components/schemas/UrlVerificationPayload' schemas: EventCallbackEnvelope: type: object description: >- The outer wrapper for all event payloads delivered by the Slack Events API. Contains metadata about the event and the inner event object. required: - token - team_id - api_app_id - event - type - event_id - event_time properties: token: type: string description: >- A shared-private callback token for verifying that the request comes from Slack. Deprecated in favor of signed secrets. team_id: type: string description: >- The unique identifier for the workspace where the event occurred. examples: - T061EG9R6 enterprise_id: type: string description: >- The unique identifier for the Enterprise Grid organization. Only present for Enterprise Grid events. api_app_id: type: string description: The unique identifier for your installed Slack application. examples: - A0PNCHHK2 type: type: string const: event_callback description: >- The type of outer event payload. Always "event_callback" for event deliveries. event: $ref: '#/components/schemas/InnerEvent' event_id: type: string description: A unique identifier for this specific event, globally unique. examples: - Ev0PV52K25 event_time: type: integer description: >- The epoch timestamp in seconds indicating when the event was dispatched. examples: - 1525215129 event_context: type: string description: >- An identifier providing installment context for the event, used with the authorizations array. authorizations: type: array description: >- An array of objects describing which app installations can see this event. Replaces the deprecated authed_users field. items: type: object properties: enterprise_id: type: string team_id: type: string user_id: type: string is_bot: type: boolean is_enterprise_install: type: boolean is_ext_shared_channel: type: boolean description: Whether this event occurred in a shared channel. context_team_id: type: string description: The workspace context team ID for this event. context_enterprise_id: type: string description: The enterprise organization context ID. InnerEvent: type: object description: >- The inner event object containing the actual event data. The specific fields depend on the event type. required: - type properties: type: type: string description: >- The specific event type name identifying what happened. event_ts: type: string description: >- The timestamp of the event, used for ordering and deduplication. user: type: string description: >- The user ID of the user who triggered the event. Not present in all event types. discriminator: propertyName: type UrlVerificationPayload: type: object description: >- Payload sent by Slack during Request URL configuration to verify ownership. The app must respond with the challenge value. required: - token - challenge - type properties: token: type: string description: Shared-private callback verification token. challenge: type: string description: >- A randomly generated string that your app must echo back to Slack in the response body. type: type: string const: url_verification MessageEvent: type: object description: >- Fired when a message is posted to a channel the app is subscribed to. Includes the message content, channel, user, and timestamp. Subtypes indicate specialized message types like bot_message, channel_join, file_share, etc. properties: type: type: string const: message channel: type: string description: The channel ID where the message was posted. user: type: string description: The user ID of the message author. text: type: string description: The text content of the message. ts: type: string description: The unique timestamp identifier for the message. event_ts: type: string channel_type: type: string description: >- The type of channel (channel, group, im, mpim). enum: - channel - group - im - mpim subtype: type: string description: >- An optional subtype for specialized message types such as bot_message, channel_join, channel_leave, me_message, file_share, thread_broadcast, etc. thread_ts: type: string description: Thread parent timestamp if this is a threaded reply. blocks: type: array description: Block Kit layout blocks in the message. items: type: object files: type: array description: Files attached to the message. items: type: object bot_id: type: string description: Bot ID if the message was posted by a bot. AppMentionEvent: type: object description: >- Fired when your app is mentioned in a message using @app_name. Useful for building apps that respond when directly mentioned. properties: type: type: string const: app_mention user: type: string description: The user ID of the user who mentioned the app. text: type: string description: The full text of the message containing the mention. ts: type: string channel: type: string description: The channel where the mention occurred. event_ts: type: string ReactionAddedEvent: type: object description: >- Fired when a reaction emoji is added to a message, file, or file comment. properties: type: type: string const: reaction_added user: type: string description: The user ID of the user who added the reaction. reaction: type: string description: The emoji name without colons. item_user: type: string description: The user ID of the user who authored the item being reacted to. item: type: object description: The item that was reacted to. properties: type: type: string description: The type of item (message, file, file_comment). enum: - message - file - file_comment channel: type: string ts: type: string file: type: string event_ts: type: string ReactionRemovedEvent: type: object description: Fired when a reaction emoji is removed from an item. properties: type: type: string const: reaction_removed user: type: string reaction: type: string item_user: type: string item: type: object properties: type: type: string channel: type: string ts: type: string file: type: string event_ts: type: string ChannelCreatedEvent: type: object description: Fired when a new channel is created in the workspace. properties: type: type: string const: channel_created channel: type: object properties: id: type: string name: type: string created: type: integer creator: type: string is_channel: type: boolean is_shared: type: boolean name_normalized: type: string event_ts: type: string ChannelArchiveEvent: type: object description: Fired when a channel is archived. properties: type: type: string const: channel_archive channel: type: string description: The channel ID that was archived. user: type: string description: The user ID of the user who archived the channel. event_ts: type: string ChannelDeletedEvent: type: object description: Fired when a channel is deleted. properties: type: type: string const: channel_deleted channel: type: string description: The channel ID that was deleted. event_ts: type: string ChannelRenameEvent: type: object description: Fired when a channel is renamed. properties: type: type: string const: channel_rename channel: type: object properties: id: type: string name: type: string name_normalized: type: string created: type: integer is_channel: type: boolean is_mpim: type: boolean event_ts: type: string MemberJoinedChannelEvent: type: object description: Fired when a user joins a channel. properties: type: type: string const: member_joined_channel user: type: string description: The user ID of the member who joined. channel: type: string description: The channel ID that was joined. channel_type: type: string description: The type of channel. enum: - C - G team: type: string description: The team ID. inviter: type: string description: The user ID of the person who invited the member, if applicable. event_ts: type: string MemberLeftChannelEvent: type: object description: Fired when a user leaves a channel. properties: type: type: string const: member_left_channel user: type: string description: The user ID of the member who left. channel: type: string description: The channel ID that was left. channel_type: type: string enum: - C - G team: type: string event_ts: type: string TeamJoinEvent: type: object description: Fired when a new member joins the workspace. properties: type: type: string const: team_join user: type: object description: >- The user object for the new team member. Contains the same fields as the users.info response. properties: id: type: string team_id: type: string name: type: string real_name: type: string is_bot: type: boolean profile: type: object event_ts: type: string UserChangeEvent: type: object description: >- Fired when a user's profile information or status is updated. properties: type: type: string const: user_change user: type: object description: The updated user object. properties: id: type: string team_id: type: string name: type: string real_name: type: string profile: type: object event_ts: type: string PinAddedEvent: type: object description: Fired when a message is pinned in a channel. properties: type: type: string const: pin_added user: type: string description: The user ID of the user who pinned the item. channel_id: type: string description: The channel ID where the item was pinned. item: type: object description: The item that was pinned. event_ts: type: string PinRemovedEvent: type: object description: Fired when a pinned message is unpinned from a channel. properties: type: type: string const: pin_removed user: type: string channel_id: type: string item: type: object event_ts: type: string FileSharedEvent: type: object description: Fired when a file is shared into a channel. properties: type: type: string const: file_shared file_id: type: string description: The unique identifier for the shared file. user_id: type: string description: The user who shared the file. file: type: object description: A partial file object. properties: id: type: string channel_id: type: string event_ts: type: string FileCreatedEvent: type: object description: Fired when a file is created. properties: type: type: string const: file_created file_id: type: string user_id: type: string file: type: object properties: id: type: string event_ts: type: string AppHomeOpenedEvent: type: object description: >- Fired when a user opens the app's App Home tab. Used to dynamically publish views. properties: type: type: string const: app_home_opened user: type: string description: The user who opened the App Home. channel: type: string description: The DM channel between the user and the app. tab: type: string description: The tab that was opened (home or messages). enum: - home - messages view: type: object description: >- The current view object for the App Home, if one was previously published. event_ts: type: string LinkSharedEvent: type: object description: >- Fired when a message containing URLs from your app's registered domains is posted. Used to provide custom link unfurling. properties: type: type: string const: link_shared channel: type: string user: type: string message_ts: type: string thread_ts: type: string links: type: array description: Array of link objects found in the message. items: type: object properties: domain: type: string url: type: string format: uri event_ts: type: string EmojiChangedEvent: type: object description: >- Fired when a custom emoji is added, renamed, or removed from the workspace. properties: type: type: string const: emoji_changed subtype: type: string description: The type of change. enum: - add - remove - rename name: type: string description: The name of the emoji. names: type: array description: Array of emoji names (for remove events). items: type: string value: type: string description: The URL of the emoji image (for add events). old_name: type: string description: The old name (for rename events). new_name: type: string description: The new name (for rename events). event_ts: type: string TokensRevokedEvent: type: object description: >- Fired when API tokens belonging to your app are revoked. Allows apps to clean up stored tokens. properties: type: type: string const: tokens_revoked tokens: type: object properties: oauth: type: array description: Array of revoked OAuth token user IDs. items: type: string bot: type: array description: Array of revoked bot token user IDs. items: type: string event_ts: type: string AppUninstalledEvent: type: object description: >- Fired when your app is uninstalled from a workspace. Allows cleanup of stored data and tokens. properties: type: type: string const: app_uninstalled event_ts: type: string