0
# Calls API
1

2
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.
3

4
## Capabilities
5

6
### Call User Types
7

8
Union type representing all possible user types in Slack Calls.
9

10
```typescript { .api }
11
type CallUser = CallUserSlack | CallUserExternal;
12
```
13

14
### Slack Workspace Users
15

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

18
```typescript { .api }
19
interface CallUserSlack {
20
  slack_id: string;
21
}
22
```
23

24
**Usage Example:**
25

26
```typescript
27
import { CallUserSlack } from "@slack/types";
28

29
const slackUser: CallUserSlack = {
30
  slack_id: "U1234567890"
31
};
32
```
33

34
### External Users
35

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

38
```typescript { .api }
39
interface CallUserExternal {
40
  external_id: string;
41
  display_name: string;
42
  avatar_url?: string;
43
}
44
```
45

46
**Usage Example:**
47

48
```typescript
49
import { CallUserExternal } from "@slack/types";
50

51
const externalUser: CallUserExternal = {
52
  external_id: "ext_user_12345",
53
  display_name: "Jane Smith",
54
  avatar_url: "https://example.com/avatars/jane-smith.png"
55
};
56
```
57

58
## Usage Patterns
59

60
### Mixed Participant Lists
61

62
Calls often include both Slack users and external participants:
63

64
```typescript
65
import { CallUser } from "@slack/types";
66

67
const callParticipants: CallUser[] = [
68
  // Slack workspace user
69
  {
70
    slack_id: "U1234567890"
71
  },
72
  // External user with avatar
73
  {
74
    external_id: "client_001",
75
    display_name: "John Client",
76
    avatar_url: "https://client-portal.com/avatars/john.jpg"
77
  },
78
  // External user without avatar
79
  {
80
    external_id: "vendor_user_42",
81
    display_name: "Sarah from Vendor Corp"
82
  }
83
];
84
```
85

86
### Call Block Integration
87

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

90
```typescript
91
import { CallUser, SectionBlock } from "@slack/types";
92

93
function createCallSummaryBlock(participants: CallUser[]): SectionBlock {
94
  const participantNames = participants.map(user => {
95
    if ('slack_id' in user) {
96
      return `<@${user.slack_id}>`;
97
    } else {
98
      return user.display_name;
99
    }
100
  }).join(', ');
101

102
  return {
103
    type: "section",
104
    text: {
105
      type: "mrkdwn",
106
      text: `*Call Participants:* ${participantNames}`
107
    }
108
  };
109
}
110
```
111

112
### Discriminating User Types
113

114
Use type guards to differentiate between user types:
115

116
```typescript
117
import { CallUser, CallUserSlack, CallUserExternal } from "@slack/types";
118

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

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

127
function formatUserForDisplay(user: CallUser): string {
128
  if (isSlackUser(user)) {
129
    return `<@${user.slack_id}>`;
130
  } else {
131
    return user.display_name;
132
  }
133
}
134
```
135

136
## API Integration
137

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

140
### Call Creation
141

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

144
```typescript
145
// Example API call structure (not part of @slack/types)
146
const callData = {
147
  external_unique_id: "call_12345",
148
  join_url: "https://zoom.us/j/123456789",
149
  title: "Project Kickoff Meeting",
150
  users: [
151
    { slack_id: "U1234567890" },
152
    { slack_id: "U0987654321" },
153
    {
154
      external_id: "client_001",
155
      display_name: "Client Representative",
156
      avatar_url: "https://client.com/avatar.png"
157
    }
158
  ] as CallUser[]
159
};
160
```
161

162
### Call Updates
163

164
Update call information including participant changes:
165

166
```typescript
167
const updatedParticipants: CallUser[] = [
168
  { slack_id: "U1234567890" },
169
  {
170
    external_id: "new_participant",
171
    display_name: "Late Joiner",
172
    avatar_url: "https://example.com/avatars/late-joiner.png"
173
  }
174
];
175
```
176

177
## Properties Details
178

179
### Slack User Properties
180

181
- **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.
182

183
### External User Properties
184

185
- **external_id**: A unique identifier created by your application to represent external users. This should be consistent across calls for the same external user.
186
- **display_name**: The name displayed in the Slack call interface. Should be the user's full name or recognizable identifier.
187
- **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.
188

189
## Best Practices
190

191
### User Identification
192

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

197
### Avatar Images
198

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

203
### Call Management
204

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

209
## Integration Examples
210

211
### Conference Bridge Integration
212

213
```typescript
214
import { CallUser } from "@slack/types";
215

216
interface ConferenceBridgeParticipant {
217
  phoneNumber?: string;
218
  slackUserId?: string;
219
  displayName: string;
220
  avatarUrl?: string;
221
}
222

223
function mapBridgeParticipants(
224
  bridgeParticipants: ConferenceBridgeParticipant[]
225
): CallUser[] {
226
  return bridgeParticipants.map(participant => {
227
    if (participant.slackUserId) {
228
      return {
229
        slack_id: participant.slackUserId
230
      };
231
    } else {
232
      return {
233
        external_id: participant.phoneNumber || `external_${Date.now()}`,
234
        display_name: participant.displayName,
235
        avatar_url: participant.avatarUrl
236
      };
237
    }
238
  });
239
}
240
```
241

242
### Video Conferencing Integration
243

244
```typescript
245
import { CallUser } from "@slack/types";
246

247
interface VideoCallParticipant {
248
  userId: string;
249
  name: string;
250
  email?: string;
251
  avatarUrl?: string;
252
  isSlackUser: boolean;
253
  slackId?: string;
254
}
255

256
function convertVideoParticipants(
257
  videoParticipants: VideoCallParticipant[]
258
): CallUser[] {
259
  return videoParticipants.map(participant => {
260
    if (participant.isSlackUser && participant.slackId) {
261
      return {
262
        slack_id: participant.slackId
263
      };
264
    } else {
265
      return {
266
        external_id: participant.userId,
267
        display_name: participant.name,
268
        avatar_url: participant.avatarUrl
269
      };
270
    }
271
  });
272
}
273
```