Skip to main content

Actions

The ballerinax/slack package exposes the following clients:

ClientPurpose
ClientProvides access to all Slack Web API methods for messaging, conversations, users, files, search, reactions, pins, and workspace administration.

Client

Provides access to all Slack Web API methods for messaging, conversations, users, files, search, reactions, pins, and workspace administration.

Configuration

FieldTypeDefaultDescription
authhttp:BearerTokenConfig|OAuth2RefreshTokenGrantConfigRequiredAuthentication configuration: a bearer token record {token: "xoxb-..."} or an OAuth 2.0 refresh token grant config.
httpVersionhttp:HttpVersionHTTP_2_0HTTP protocol version to use.
timeoutdecimal30Request timeout in seconds.
retryConfighttp:RetryConfig()Retry configuration for failed requests.
secureSockethttp:ClientSecureSocket()SSL/TLS configuration.
proxyhttp:ProxyConfig()Proxy server configuration.
validationbooleantrueEnable response payload validation against the Slack API schema.
laxDataBindingbooleantrueAllow lax data binding for API responses with extra fields.

Initializing the client

import ballerinax/slack;

configurable string token = ?;

slack:Client slackClient = check new ({
auth: {
token: token
}
});

Operations

Messaging

Post a message to a channel

Sends a message to a public channel, private channel, or direct message.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID or name where the message will be posted (e.g., "C1234567890" or "general").
textstringNoMessage text. Required when blocks is not provided.
blocksstringNoA JSON-encoded array of Block Kit layout blocks.
thread_tsstringNoTimestamp of the parent message to reply to as a thread.
mrkdwnbooleanNoWhether to parse Slack markdown in the message text.

Returns: ChatPostMessageResponse|error

Sample code:

slack:ChatPostMessageResponse response = check slackClient->/chat\.postMessage.post({
channel: "C1234567890",
text: "Hello from Ballerina!"
});

Sample response:

{
"ok": true,
"channel": "C1234567890",
"ts": "1720000000.123456",
"message": {
"type": "message",
"text": "Hello from Ballerina!",
"user": "U0000BOT",
"ts": "1720000000.123456"
}
}
Update a message

Updates the text of an existing message in a channel.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID containing the message.
tsstringYesTimestamp of the message to update.
textstringNoNew message text.

Returns: ChatUpdateResponse|error

Sample code:

slack:ChatUpdateResponse response = check slackClient->/chat\.update.post({
channel: "C1234567890",
ts: "1720000000.123456",
text: "Updated: deployment completed successfully."
});

Sample response:

{
"ok": true,
"channel": "C1234567890",
"ts": "1720000000.123456",
"text": "Updated: deployment completed successfully."
}
Delete a message

Deletes a message from a channel.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID containing the message.
tsstringYesTimestamp of the message to delete.

Returns: ChatDeleteResponse|error

Sample code:

slack:ChatDeleteResponse response = check slackClient->/chat\.delete.post({
channel: "C1234567890",
ts: "1720000000.123456"
});

Sample response:

{
"ok": true,
"channel": "C1234567890",
"ts": "1720000000.123456"
}
Get a message permalink

Retrieves a permanent, public URL for a specific message.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID containing the message.
message_tsstringYesTimestamp of the message.

Returns: ChatGetPermalinkResponse|error

Sample code:

slack:ChatGetPermalinkResponse response = check slackClient->/chat\.getPermalink({
channel: "C1234567890",
message_ts: "1720000000.123456"
});

Sample response:

{
"ok": true,
"channel": "C1234567890",
"permalink": "https://myworkspace.slack.com/archives/C1234567890/p1720000000123456"
}
Post an ephemeral message

Sends an ephemeral message to a user in a channel: visible only to that user.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID where the ephemeral message is posted.
userstringYesUser ID of the recipient.
textstringNoMessage text.

Returns: ChatPostEphemeralResponse|error

Sample code:

slack:ChatPostEphemeralResponse response = check slackClient->/chat\.postEphemeral.post({
channel: "C1234567890",
user: "U0000001",
text: "Only you can see this reminder."
});

Sample response:

{
"ok": true,
"message_ts": "1720000001.000100"
}
Schedule a message

Schedules a message to be sent to a channel at a specified future time.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID where the message will be posted.
post_atintYesUnix timestamp (seconds) indicating when to send the message.
textstringNoMessage text.

Returns: ChatScheduleMessageResponse|error

Sample code:

slack:ChatScheduleMessageResponse response = check slackClient->/chat\.scheduleMessage.post({
channel: "C1234567890",
post_at: 1800000000,
text: "Good morning team! Daily standup starts in 15 minutes."
});

Sample response:

{
"ok": true,
"channel": "C1234567890",
"scheduled_message_id": "Q1234ABCD",
"post_at": 1800000000,
"message": {
"text": "Good morning team! Daily standup starts in 15 minutes.",
"type": "delayed_message"
}
}
List scheduled messages

Returns a list of scheduled messages.

Parameters:

NameTypeRequiredDescription
channelstringNoFilter to a specific channel ID.
limitintNoMaximum number of results to return.

Returns: ChatScheduledMessagesListResponse|error

Sample code:

slack:ChatScheduledMessagesListResponse response = check slackClient->/chat\.scheduledMessages\.list({
channel: "C1234567890"
});

Sample response:

{
"ok": true,
"scheduled_messages": [
{
"id": "Q1234ABCD",
"channel_id": "C1234567890",
"post_at": 1800000000,
"date_created": 1720000000,
"text": "Good morning team! Daily standup starts in 15 minutes."
}
],
"response_metadata": {"next_cursor": ""}
}

Conversations

List all conversations

Returns a list of all channels in the Slack workspace.

Parameters:

NameTypeRequiredDescription
typesstringNoComma-separated list of channel types to include: public_channel, private_channel, mpim, im.
limitintNoMaximum number of channels to return per page.
exclude_archivedbooleanNoExclude archived channels from the results.
cursorstringNoPagination cursor returned from a previous response.

Returns: ConversationsListResponse|error

Sample code:

slack:ConversationsListResponse response = check slackClient->/conversations\.list({
types: "public_channel",
exclude_archived: true,
limit: 100
});

Sample response:

{
"ok": true,
"channels": [
{"id": "C1234567890", "name": "general", "is_channel": true, "num_members": 42, "is_archived": false},
{"id": "C0987654321", "name": "random", "is_channel": true, "num_members": 38, "is_archived": false}
],
"response_metadata": {"next_cursor": "dGVhbTpDMDYxRkE3NkQ="}
}
Get conversation message history

Fetches a conversation's message history including all messages posted in the channel.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID to fetch history from.
limitintNoMaximum number of messages to return.
oldeststringNoOnly return messages after this Unix timestamp.
lateststringNoOnly return messages before this Unix timestamp.
cursorstringNoPagination cursor.

Returns: ConversationsHistoryResponse|error

Sample code:

slack:ConversationsHistoryResponse response = check slackClient->/conversations\.history({
channel: "C1234567890",
limit: 5
});

Sample response:

{
"ok": true,
"messages": [
{"type": "message", "user": "U0000001", "text": "Deployment complete!", "ts": "1720000100.000200"},
{"type": "message", "user": "U0000002", "text": "Great work everyone", "ts": "1720000000.123456"}
],
"has_more": true,
"response_metadata": {"next_cursor": "bmV4dF90czoxNzIwMDAwMDAwLjEyMzQ1Ng=="}
}
Get conversation thread replies

Retrieves all replies in a message thread.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID containing the thread.
tsstringYesTimestamp of the parent (thread root) message.
limitintNoMaximum number of replies to return.

Returns: ConversationsRepliesResponse|error

Sample code:

slack:ConversationsRepliesResponse response = check slackClient->/conversations\.replies({
channel: "C1234567890",
ts: "1720000000.123456"
});

Sample response:

{
"ok": true,
"messages": [
{"type": "message", "user": "U0000001", "text": "Any updates on the release?", "ts": "1720000000.123456", "reply_count": 2},
{"type": "message", "user": "U0000002", "text": "Almost done, deploying now", "ts": "1720000010.000100"},
{"type": "message", "user": "U0000003", "text": "Tests are passing!", "ts": "1720000020.000200"}
],
"has_more": false
}
Create a conversation

Creates a new public or private channel in the workspace.

Parameters:

NameTypeRequiredDescription
namestringYesName of the channel to create (lowercase, no spaces).
is_privatebooleanNoSet to true to create a private channel.

Returns: ConversationsCreateResponse|error

Sample code:

slack:ConversationsCreateResponse response = check slackClient->/conversations\.create.post({
name: "project-phoenix",
is_private: false
});

Sample response:

{
"ok": true,
"channel": {
"id": "C0000NEW01",
"name": "project-phoenix",
"is_channel": true,
"is_private": false,
"created": 1720000000,
"num_members": 1
}
}
Get conversation info

Retrieves detailed information about a specific conversation.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID to retrieve information about.

Returns: ConversationsInfoResponse|error

Sample code:

slack:ConversationsInfoResponse response = check slackClient->/conversations\.info({
channel: "C1234567890"
});

Sample response:

{
"ok": true,
"channel": {
"id": "C1234567890",
"name": "general",
"is_channel": true,
"is_private": false,
"num_members": 42,
"purpose": {"value": "Company-wide announcements and news"},
"topic": {"value": "Q3 planning sprint"}
}
}
Invite users to a conversation

Invites one or more users to join a channel.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID to invite users to.
usersstringYesComma-separated list of user IDs to invite.

Returns: ConversationsInviteErrorResponse|error

Sample code:

slack:ConversationsInviteErrorResponse response = check slackClient->/conversations\.invite.post({
channel: "C0000NEW01",
users: "U0000001,U0000002,U0000003"
});

Sample response:

{
"ok": true,
"channel": {
"id": "C0000NEW01",
"name": "project-phoenix",
"num_members": 4
}
}
Get conversation members

Retrieves the list of member user IDs for a conversation.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID to retrieve members from.
limitintNoMaximum number of members to return per page.
cursorstringNoPagination cursor.

Returns: ConversationsMembersResponse|error

Sample code:

slack:ConversationsMembersResponse response = check slackClient->/conversations\.members({
channel: "C1234567890",
limit: 50
});

Sample response:

{
"ok": true,
"members": ["U0000001", "U0000002", "U0000003", "U0000BOT"],
"response_metadata": {"next_cursor": ""}
}
Set conversation topic

Sets the topic for a conversation.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID.
topicstringYesNew topic text.

Returns: ConversationsSetTopicResponse|error

Sample code:

slack:ConversationsSetTopicResponse response = check slackClient->/conversations\.setTopic.post({
channel: "C1234567890",
topic: "Q3 sprint: focus on performance improvements"
});

Sample response:

{
"ok": true,
"channel": {
"id": "C1234567890",
"topic": {
"value": "Q3 sprint: focus on performance improvements",
"creator": "U0000BOT",
"last_set": 1720000000
}
}
}
Archive a conversation

Archives a conversation so it can no longer receive messages.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID to archive.

Returns: ConversationsArchiveResponse|error

Sample code:

slack:ConversationsArchiveResponse response = check slackClient->/conversations\.archive.post({
channel: "C0000OLD01"
});

Sample response:

{"ok": true}

Users

List all users in the workspace

Returns a list of all users in the workspace, including deactivated accounts.

Parameters:

NameTypeRequiredDescription
limitintNoMaximum number of users to return per page.
cursorstringNoPagination cursor.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/users\.list({limit: 100});

Sample response:

{
"ok": true,
"members": [
{"id": "U0000001", "name": "alice", "real_name": "Alice Smith", "is_bot": false, "deleted": false},
{"id": "U0000002", "name": "bob", "real_name": "Bob Jones", "is_bot": false, "deleted": false},
{"id": "U0000BOT", "name": "ballerina-bot", "real_name": "Ballerina Bot", "is_bot": true, "deleted": false}
],
"response_metadata": {"next_cursor": ""}
}
Get user info

Retrieves detailed information about a specific user.

Parameters:

NameTypeRequiredDescription
userstringYesUser ID to retrieve.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/users\.info({user: "U0000001"});

Sample response:

{
"ok": true,
"user": {
"id": "U0000001",
"name": "alice",
"real_name": "Alice Smith",
"is_bot": false,
"profile": {
"email": "[email protected]",
"display_name": "Alice",
"title": "Senior Software Engineer",
"phone": "+1-555-0100"
}
}
}
Get user presence

Gets the current presence status of a user.

Parameters:

NameTypeRequiredDescription
userstringYesUser ID to check presence for.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/users\.getPresence({user: "U0000001"});

Sample response:

{
"ok": true,
"presence": "active",
"online": true,
"auto_away": false,
"manual_away": false,
"connection_count": 1,
"last_activity": 1720000000
}
Get conversations for a user

Lists all conversations the calling user or a specified user may access.

Parameters:

NameTypeRequiredDescription
userstringNoUser ID whose conversations to list. Defaults to the authenticated user.
typesstringNoComma-separated list of channel types: public_channel, private_channel, mpim, im.
limitintNoMaximum number of conversations to return.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/users\.conversations({
user: "U0000001",
types: "public_channel,private_channel"
});

Sample response:

{
"ok": true,
"channels": [
{"id": "C1234567890", "name": "general"},
{"id": "C0987654321", "name": "team-dev"},
{"id": "C0000NEW01", "name": "project-phoenix"}
],
"response_metadata": {"next_cursor": ""}
}

Files

Upload a file

Uploads a file to Slack and optionally shares it to one or more channels.

Parameters:

NameTypeRequiredDescription
channelsstringNoComma-separated list of channel IDs to share the file to.
contentstringNoFile content as a string (for text-based files).
filenamestringNoName of the file.
titlestringNoTitle of the file displayed in Slack.
initial_commentstringNoMessage text to post alongside the file.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/files\.upload.post({
channels: "C1234567890",
content: "Server: api-prod\nStatus: OK\nUptime: 99.98%",
filename: "health-report.txt",
title: "Daily Health Report",
initial_comment: "Automated health check results for today."
});

Sample response:

{
"ok": true,
"file": {
"id": "F0000FILE1",
"name": "health-report.txt",
"title": "Daily Health Report",
"filetype": "text",
"size": 45,
"url_private": "https://files.slack.com/files-pri/T0001/F0000FILE1/health-report.txt",
"permalink": "https://myworkspace.slack.com/files/U0000BOT/F0000FILE1/health-report.txt"
}
}
List files

Returns a list of files within the workspace, optionally filtered by channel or user.

Parameters:

NameTypeRequiredDescription
channelstringNoFilter files shared in this channel ID.
userstringNoFilter files uploaded by this user ID.
countintNoNumber of files to return per page.
typesstringNoFilter by file types (e.g., images, pdfs, snippets, spaces).

Returns: FilesListResponse|error

Sample code:

slack:FilesListResponse response = check slackClient->/files\.list({
channel: "C1234567890",
count: 20
});

Sample response:

{
"ok": true,
"files": [
{"id": "F0000FILE1", "name": "health-report.txt", "title": "Daily Health Report", "filetype": "text", "size": 45},
{"id": "F0000FILE2", "name": "architecture.png", "title": "System Architecture", "filetype": "png", "size": 204800}
],
"paging": {"count": 20, "total": 2, "page": 1, "pages": 1}
}
Get file info

Gets detailed information about a specific file.

Parameters:

NameTypeRequiredDescription
filestringYesFile ID to retrieve.

Returns: FilesInfoResponse|error

Sample code:

slack:FilesInfoResponse response = check slackClient->/files\.info({file: "F0000FILE1"});

Sample response:

{
"ok": true,
"file": {
"id": "F0000FILE1",
"name": "health-report.txt",
"title": "Daily Health Report",
"filetype": "text",
"size": 45,
"created": 1720000000,
"url_private": "https://files.slack.com/files-pri/T0001/F0000FILE1/health-report.txt",
"channels": ["C1234567890"]
}
}
Delete a file

Deletes a file from Slack.

Parameters:

NameTypeRequiredDescription
filestringYesFile ID to delete.

Returns: FilesDeleteResponse|error

Sample code:

slack:FilesDeleteResponse response = check slackClient->/files\.delete.post({
file: "F0000FILE1"
});

Sample response:

{"ok": true}
Search messages

Searches for messages matching a query string across the workspace.

Parameters:

NameTypeRequiredDescription
querystringYesSearch query string. Supports Slack's search modifiers (e.g., in:#channel, from:@user).
countintNoNumber of results per page.
pageintNoPage number of results.
sortstringNoSort results by score (relevance) or timestamp.
sort_dirstringNoSort direction: asc or desc.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/search\.messages({
query: "deployment failed in:#alerts",
count: 10,
sort: "timestamp",
sort_dir: "desc"
});

Sample response:

{
"ok": true,
"messages": {
"total": 2,
"pagination": {"total_count": 2, "page": 1, "per_page": 10, "page_count": 1},
"matches": [
{
"type": "message",
"text": "deployment failed on prod: rolling back now",
"channel": {"id": "C1234567890", "name": "alerts"},
"ts": "1720000000.000100",
"username": "alice"
}
]
}
}
Search files

Searches for files matching a query string across the workspace.

Parameters:

NameTypeRequiredDescription
querystringYesSearch query string.
countintNoNumber of results per page.
pageintNoPage number.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/search\.files({
query: "Q3 report",
count: 10
});

Sample response:

{
"ok": true,
"files": {
"total": 1,
"matches": [
{"id": "F0000FILE1", "name": "q3-report.txt", "title": "Q3 Revenue Report", "filetype": "text", "size": 1024}
],
"pagination": {"total_count": 1, "page": 1}
}
}

Reactions

Add a reaction to a message

Adds an emoji reaction to a message.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID containing the message.
namestringYesEmoji name without surrounding colons (e.g., "thumbsup", "tada").
timestampstringYesTimestamp of the message to react to.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/reactions\.add.post({
channel: "C1234567890",
name: "white_check_mark",
timestamp: "1720000000.123456"
});

Sample response:

{"ok": true}
Remove a reaction from a message

Removes an emoji reaction previously added to a message.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID containing the message.
namestringYesEmoji name to remove.
timestampstringYesTimestamp of the reacted message.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/reactions\.remove.post({
channel: "C1234567890",
name: "white_check_mark",
timestamp: "1720000000.123456"
});

Sample response:

{"ok": true}
Get reactions on a message

Gets all emoji reactions for a specified message.

Parameters:

NameTypeRequiredDescription
channelstringNoChannel ID (required when retrieving reactions on a message).
timestampstringNoMessage timestamp.
filestringNoFile ID (use instead of channel and timestamp for file reactions).

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/reactions\.get({
channel: "C1234567890",
timestamp: "1720000000.123456"
});

Sample response:

{
"ok": true,
"type": "message",
"message": {
"text": "Deployment complete!",
"ts": "1720000000.123456",
"reactions": [
{"name": "white_check_mark", "count": 5, "users": ["U0000001", "U0000002", "U0000003"]},
{"name": "tada", "count": 2, "users": ["U0000001", "U0000002"]}
]
}
}

Pins

Pin a message to a channel

Pins a message to a channel for quick reference.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID where the item will be pinned.
timestampstringNoTimestamp of the message to pin.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/pins\.add.post({
channel: "C1234567890",
timestamp: "1720000000.123456"
});

Sample response:

{"ok": true}
List pinned items in a channel

Lists all items pinned to a channel.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID to list pinned items from.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/pins\.list({channel: "C1234567890"});

Sample response:

{
"ok": true,
"items": [
{
"type": "message",
"message": {
"text": "Team processes and guidelines: see wiki link in description",
"ts": "1720000000.123456",
"user": "U0000001"
},
"channel": "C1234567890",
"created": 1720000100,
"created_by": "U0000001"
}
]
}
Unpin an item from a channel

Removes a pinned item from a channel.

Parameters:

NameTypeRequiredDescription
channelstringYesChannel ID.
timestampstringNoTimestamp of the message to unpin.

Returns: DefaultSuccessResponse|error

Sample code:

slack:DefaultSuccessResponse response = check slackClient->/pins\.remove.post({
channel: "C1234567890",
timestamp: "1720000000.123456"
});

Sample response:

{"ok": true}

Auth & API

Test authentication

Verifies the authentication token and returns information about the authenticated user and workspace.

Returns: AuthTestResponse|error

Sample code:

slack:AuthTestResponse response = check slackClient->/auth\.test();

Sample response:

{
"ok": true,
"url": "https://myworkspace.slack.com/",
"team": "My Workspace",
"user": "ballerina-bot",
"team_id": "T0000001",
"user_id": "U0000BOT",
"bot_id": "B0000001",
"is_enterprise_install": false
}
Revoke an access token

Revokes an access token, invalidating it for future API calls.

Parameters:

NameTypeRequiredDescription
testbooleanNoSet to true for a dry run: the token is not actually revoked.

Returns: AuthRevokeResponse|error

Sample code:

slack:AuthRevokeResponse response = check slackClient->/auth\.revoke();

Sample response:

{"ok": true, "revoked": true}
Get bot info

Gets information about a bot user associated with the workspace.

Parameters:

NameTypeRequiredDescription
botstringNoBot ID to retrieve. Defaults to the bot associated with the current token.

Returns: BotsInfoResponse|error

Sample code:

slack:BotsInfoResponse response = check slackClient->/bots\.info();

Sample response:

{
"ok": true,
"bot": {
"id": "B0000001",
"deleted": false,
"name": "Ballerina Bot",
"app_id": "A0000001",
"user_id": "U0000BOT",
"icons": {
"image_36": "https://a.slack-edge.com/80588/img/slackbot_36.png",
"image_48": "https://a.slack-edge.com/80588/img/slackbot_48.png"
}
}
}