tessl/npm-slack--types

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

1.11x

Overview

Eval results

Files

Calls API

Name: tessl/npm-slack--types
Rating: 0.94 (1 reviews)
Author: tessl

The Slack Calls API enables third-party applications to display call information and participants within the Slack client. This module provides TypeScript definitions for representing users in Slack Calls.

Capabilities

Call User Types

Union type representing all possible user types in Slack Calls.

type CallUser = CallUserSlack | CallUserExternal;

Slack Workspace Users

Represents users from the same Slack workspace participating in a call.

interface CallUserSlack {
  slack_id: string;
}

Usage Example:

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

const slackUser: CallUserSlack = {
  slack_id: "U1234567890"
};

External Users

Represents users from outside the Slack workspace participating in a call.

interface CallUserExternal {
  external_id: string;
  display_name: string;
  avatar_url?: string;
}

Usage Example:

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

const externalUser: CallUserExternal = {
  external_id: "ext_user_12345",
  display_name: "Jane Smith",
  avatar_url: "https://example.com/avatars/jane-smith.png"
};

Usage Patterns

Mixed Participant Lists

Calls often include both Slack users and external participants:

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

const callParticipants: CallUser[] = [
  // Slack workspace user
  {
    slack_id: "U1234567890"
  },
  // External user with avatar
  {
    external_id: "client_001",
    display_name: "John Client",
    avatar_url: "https://client-portal.com/avatars/john.jpg"
  },
  // External user without avatar
  {
    external_id: "vendor_user_42",
    display_name: "Sarah from Vendor Corp"
  }
];

Call Block Integration

Call user types are typically used within call-related Block Kit blocks:

import { CallUser, SectionBlock } from "@slack/types";

function createCallSummaryBlock(participants: CallUser[]): SectionBlock {
  const participantNames = participants.map(user => {
    if ('slack_id' in user) {
      return `<@${user.slack_id}>`;
    } else {
      return user.display_name;
    }
  }).join(', ');

  return {
    type: "section",
    text: {
      type: "mrkdwn",
      text: `*Call Participants:* ${participantNames}`
    }
  };
}

Discriminating User Types

Use type guards to differentiate between user types:

import { CallUser, CallUserSlack, CallUserExternal } from "@slack/types";

function isSlackUser(user: CallUser): user is CallUserSlack {
  return 'slack_id' in user;
}

function isExternalUser(user: CallUser): user is CallUserExternal {
  return 'external_id' in user;
}

function formatUserForDisplay(user: CallUser): string {
  if (isSlackUser(user)) {
    return `<@${user.slack_id}>`;
  } else {
    return user.display_name;
  }
}

API Integration

These types are primarily used with Slack's Web API methods related to calls:

Call Creation

When creating a call, you specify participants using these user types:

// Example API call structure (not part of @slack/types)
const callData = {
  external_unique_id: "call_12345",
  join_url: "https://zoom.us/j/123456789",
  title: "Project Kickoff Meeting",
  users: [
    { slack_id: "U1234567890" },
    { slack_id: "U0987654321" },
    {
      external_id: "client_001",
      display_name: "Client Representative",
      avatar_url: "https://client.com/avatar.png"
    }
  ] as CallUser[]
};

Call Updates

Update call information including participant changes:

const updatedParticipants: CallUser[] = [
  { slack_id: "U1234567890" },
  {
    external_id: "new_participant",
    display_name: "Late Joiner",
    avatar_url: "https://example.com/avatars/late-joiner.png"
  }
];

Properties Details

Slack User Properties

slack_id: The encoded Slack user ID (e.g., "U1234ABCD"). This should be used when you have access to the Slack user ID and the user is a member of the workspace.

External User Properties

external_id: A unique identifier created by your application to represent external users. This should be consistent across calls for the same external user.
display_name: The name displayed in the Slack call interface. Should be the user's full name or recognizable identifier.
avatar_url: Optional URL to the user's avatar image. If provided, Slack will display this image in the call interface. The image should be reasonably sized and publicly accessible.

Best Practices

User Identification

Prefer Slack IDs: When possible, use CallUserSlack for workspace members as it provides better integration with Slack's user management.
Consistent External IDs: Use consistent external_id values across calls for the same external user to enable proper user recognition.
Meaningful Display Names: Choose display names that help Slack users identify external participants (e.g., "John Smith (Customer)" rather than just "John").

Avatar Images

Optimal Size: Use square images around 128x128 pixels for best display quality.
Public URLs: Ensure avatar URLs are publicly accessible and don't require authentication.
Fallback Handling: Don't rely on avatars being displayed - some clients may not support them.

Call Management

User Privacy: Only include users who have consented to be displayed in the Slack call interface.
Real-time Updates: Update participant lists as users join or leave calls to maintain accuracy.
Error Handling: Handle cases where Slack user IDs may be invalid or external users may not have complete information.

Integration Examples

Conference Bridge Integration

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

interface ConferenceBridgeParticipant {
  phoneNumber?: string;
  slackUserId?: string;
  displayName: string;
  avatarUrl?: string;
}

function mapBridgeParticipants(
  bridgeParticipants: ConferenceBridgeParticipant[]
): CallUser[] {
  return bridgeParticipants.map(participant => {
    if (participant.slackUserId) {
      return {
        slack_id: participant.slackUserId
      };
    } else {
      return {
        external_id: participant.phoneNumber || `external_${Date.now()}`,
        display_name: participant.displayName,
        avatar_url: participant.avatarUrl
      };
    }
  });
}

Video Conferencing Integration

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

interface VideoCallParticipant {
  userId: string;
  name: string;
  email?: string;
  avatarUrl?: string;
  isSlackUser: boolean;
  slackId?: string;
}

function convertVideoParticipants(
  videoParticipants: VideoCallParticipant[]
): CallUser[] {
  return videoParticipants.map(participant => {
    if (participant.isSlackUser && participant.slackId) {
      return {
        slack_id: participant.slackId
      };
    } else {
      return {
        external_id: participant.userId,
        display_name: participant.name,
        avatar_url: participant.avatarUrl
      };
    }
  });
}

Install with Tessl CLI

npx tessl i tessl/npm-slack--types