CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-slack--types

Comprehensive TypeScript type definitions for building Slack applications and integrations with the Node Slack SDK

94

1.11x
Overview
Eval results
Files

message-attachments.mddocs/

Message Attachments

Message attachments provide a legacy system for adding rich, structured content to Slack messages. While Block Kit is now the preferred approach for new development, attachments remain fully supported for backward compatibility and specific use cases.

Capabilities

Message Attachment Structure

Core interface for secondary message attachments.

interface MessageAttachment {
  blocks?: AnyBlock[];
  fallback?: string;
  color?: 'good' | 'warning' | 'danger' | string;
  pretext?: string;
  author_name?: string;
  author_link?: string;
  author_icon?: string;
  author_subname?: string;
  title?: string;
  title_link?: string;
  text?: string;
  fields?: MessageAttachmentField[];
  image_url?: string;
  thumb_url?: string;
  footer?: string;
  footer_icon?: string;
  ts?: string;
  actions?: AttachmentAction[];
  callback_id?: string;
  mrkdwn_in?: ('pretext' | 'text' | 'fields')[];
  app_unfurl_url?: string;
  is_app_unfurl?: boolean;
  app_id?: string;
  bot_id?: string;
  preview?: MessageAttachmentPreview;
}

Basic Usage Example:

import { MessageAttachment } from "@slack/types";

const attachment: MessageAttachment = {
  color: "good",
  title: "Deployment Successful",
  title_link: "https://example.com/deployment/12345",
  text: "Version 2.1.4 has been successfully deployed to production.",
  fields: [
    {
      title: "Environment",
      value: "Production",
      short: true
    },
    {
      title: "Duration",
      value: "3 minutes 42 seconds",
      short: true
    }
  ],
  footer: "Deployment Bot",
  footer_icon: "https://example.com/icons/deploy.png",
  ts: "1609459200"
};

Attachment Fields

Table-like field display within attachments.

interface MessageAttachmentField {
  title: string;
  value: string;
  short?: boolean;
}

Usage Example:

const fields: MessageAttachmentField[] = [
  {
    title: "Priority",
    value: "High",
    short: true
  },
  {
    title: "Status",
    value: "In Progress",
    short: true
  },
  {
    title: "Description",
    value: "This is a longer description that will span the full width",
    short: false
  }
];

Link Unfurls

URL-to-attachment mapping for rich link previews.

interface LinkUnfurls {
  [linkUrl: string]: MessageAttachment;
}

Usage Example:

import { LinkUnfurls } from "@slack/types";

const unfurls: LinkUnfurls = {
  "https://example.com/article/123": {
    color: "#36a64f",
    title: "How to Build Great APIs",
    title_link: "https://example.com/article/123",
    text: "A comprehensive guide to designing and implementing REST APIs that developers love to use.",
    author_name: "Jane Developer",
    author_icon: "https://example.com/avatars/jane.png",
    image_url: "https://example.com/images/api-guide.png",
    footer: "Dev Blog",
    footer_icon: "https://example.com/favicon.ico",
    ts: "1609459200"
  }
};

Attachment Properties

Visual Styling

Color Bar

Left border color to categorize or highlight attachments.

color?: 'good' | 'warning' | 'danger' | string;
  • 'good' - Green color for positive/success states
  • 'warning' - Yellow color for warning states
  • 'danger' - Red color for error/failure states
  • Custom hex color (e.g., '#439FE0')

Pretext

Text appearing above the attachment block.

pretext?: string;

Author Information

Author details displayed at the top of the attachment.

author_name?: string;
author_link?: string;
author_icon?: string;
author_subname?: string;

Usage Example:

const authorAttachment: MessageAttachment = {
  author_name: "GitHub",
  author_link: "https://github.com/user/repo",
  author_icon: "https://github.com/favicon.ico",
  title: "New Pull Request",
  text: "Feature: Add user authentication"
};

Title and Content

Main title and body content of the attachment.

title?: string;
title_link?: string;
text?: string;
fallback?: string;

The fallback property provides plain text for clients that don't support rich attachments.

Media Content

Images and thumbnails within attachments.

image_url?: string;
thumb_url?: string;
  • image_url - Large image displayed at bottom (cannot be used with thumb_url)
  • thumb_url - Small thumbnail on the right side (75px max)

Footer Information

Footer text and icon displayed at the bottom.

footer?: string;
footer_icon?: string;
ts?: string;

The ts property adds a timestamp to the footer display.

Markdown Formatting

Control which fields support markdown formatting.

mrkdwn_in?: ('pretext' | 'text' | 'fields')[];

Usage Example:

const formattedAttachment: MessageAttachment = {
  text: "*Bold text* and _italic text_ with `code`",
  mrkdwn_in: ["text"],
  fields: [
    {
      title: "Status",
      value: "*Active* :white_check_mark:",
      short: true
    }
  ]
};

Block Kit Integration

Modern attachments can include Block Kit content alongside legacy properties.

blocks?: AnyBlock[];

Hybrid Usage Example:

const modernAttachment: MessageAttachment = {
  color: "good",
  blocks: [
    {
      type: "section",
      text: {
        type: "mrkdwn",
        text: "*Deployment Status*\nVersion 2.1.4 deployed successfully"
      },
      accessory: {
        type: "button",
        text: {
          type: "plain_text",
          text: "View Logs"
        },
        action_id: "view_deployment_logs",
        url: "https://logs.example.com/deployment/12345"
      }
    }
  ],
  fallback: "Deployment successful - Version 2.1.4"
};

Legacy Interactive Components

Deprecated interactive elements for attachments (replaced by Block Kit).

actions?: AttachmentAction[];
callback_id?: string;

Note: Use Block Kit buttons and interactive elements in blocks array instead of legacy actions.

Confirmation Dialog (Legacy)

Legacy confirmation structure used in bolt-js.

interface Confirmation {
  dismiss_text?: string;
  ok_text?: string;
  text: string;
  title?: string;
}

Best Practices

When to Use Attachments

  • Link unfurling: Rich previews for external URLs
  • Legacy compatibility: Maintaining existing attachment-based integrations
  • Simple structured data: Basic field/value displays without interaction

When to Use Block Kit Instead

  • New development: All new Slack apps should use Block Kit
  • Interactive elements: Buttons, select menus, inputs
  • Complex layouts: Multi-column layouts, rich formatting
  • Accessibility: Better screen reader support

Migration Path

To migrate from attachments to Block Kit:

  1. Replace text with SectionBlock containing TextObject
  2. Replace fields with SectionBlock using fields property
  3. Replace actions with ActionsBlock containing Block Kit elements
  4. Replace title with HeaderBlock or SectionBlock with formatted text

Before (Attachment):

const legacyAttachment: MessageAttachment = {
  title: "Task Update",
  text: "Task has been completed successfully",
  fields: [
    { title: "Assignee", value: "John Doe", short: true },
    { title: "Priority", value: "High", short: true }
  ]
};

After (Block Kit):

const modernBlocks = [
  {
    type: "header",
    text: { type: "plain_text", text: "Task Update" }
  },
  {
    type: "section",
    text: { type: "plain_text", text: "Task has been completed successfully" },
    fields: [
      { type: "mrkdwn", text: "*Assignee:*\nJohn Doe" },
      { type: "mrkdwn", text: "*Priority:*\nHigh" }
    ]
  }
];

Install with Tessl CLI

npx tessl i tessl/npm-slack--types

docs

block-kit.md

calls.md

dialog.md

events.md

index.md

interactive-elements.md

message-attachments.md

message-metadata.md

views.md

tile.json