Set Channel Properties

Learn to use Slack API calls to specify different settings of conversations.

We'll cover the following

In this lesson, we’ll look at a few of the numerous endpoints of the Conversations API. If you want to manage channels with an app, this lesson will cover the essential endpoints for handling those. This lesson covers the essential endpoints that help us manage channels in Slack.

Let’s look at the following endpoints in this lesson:

  1. conversations.setPurpose: This endpoint sets the purpose of a channel.
  2. conversations.rename: This endpoint renames a channel.
  3. conversations.setTopic: This endpoint sets the topic for a channel.
  4. conversations.open: This endpoint opens or resumes a direct or multi-person direct message.
  5. conversations.leave: This endpoint leaves a channel.
  6. conversations.join: This endpoint joins an existing channel.

Change channel properties

To change channel properties, we access the following similar endpoints in the code widget:

  1. https://slack.com/api/conversations.setPurpose
  2. https://slack.com/api/conversations.rename
  3. https://slack.com/api/conversations.setTopic

Request parameters

Some of the important query parameters for these endpoints are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

channel

string

required

This parameter specifies the channel to which the message will be posted. It can be a public channel, a private group, or an IM channel (direct message). The value for this parameter can either be an encoded ID or a name of a channel.

purpose/name/topic

string

required

This adds a purpose/name/topic for the channel.

Let’s call these endpoints. Click the “Run” button to rename the channel and add a purpose and a topic.

Press + to interact
import fetch from "node-fetch";
const headerParameters = {
  Authorization: "Bearer {{TOKEN}}",
  "Content-Type": "application/json; charset=UTF-8",
};
// Defining a function to make a POST request
async function makePostRequest(url, bodyParameters, prompt) {
  try {
    const options = {
      method: "POST",
      headers: headerParameters,
      body: bodyParameters,
    };
    const response = await fetch(url, options);
    printResponse(prompt, response);
  } catch (error) {
    printError(error);
  }
}
// Defining a function to set the channel properties
async function setChannelProperties(purpose, name, topic) {
  // Updating the channel purpose
  const purposeUrl = "https://slack.com/api/conversations.setPurpose";
  const purposeBody = JSON.stringify({
    channel: "{{CHANNEL_ID_APP}}",
    purpose: purpose,
  });
  await makePostRequest(purposeUrl, purposeBody);
  // Renaming the channel
  const renameUrl = "https://slack.com/api/conversations.rename";
  const renameBody = JSON.stringify({
    channel: "{{CHANNEL_ID_APP}}",
    name: name,
  });
  await makePostRequest(renameUrl, renameBody);
  // Updating the channel topic
  const topicUrl = "https://slack.com/api/conversations.setTopic";
  const topicBody = JSON.stringify({
    channel: "{{CHANNEL_ID_APP}}",
    topic: topic,
  });
  await makePostRequest(topicUrl, topicBody);
}
// Calling the function to set channel properties
let purpose = "A channel without purpose is a channel not at all.";
let name = "updated_channel_name";
let topic = "Topic for today: Fix Bugs!";
setChannelProperties(purpose, name, topic);

Let’s look at the highlighted lines in the code widget shown above:

  • Lines 27–32: We make a call to the conversations.setPurpose endpoint.
  • Lines 35–40: We make a call to the conversations.rename endpoint.
  • Lines 43–48: We make a call to the conversations.setTopic endpoint.

Response fields

The response from these endpoints includes a channel property that contains the details for the channel that was updated.

Note: Visit this lesson to view the details of the channel object.

Open a private chat with a user

To open a chat with a user, we access the https://slack.com/api/conversations.open and the https://slack.com/api/conversations.close endpoints. As chat.postMessage doesn’t take user IDs as a parameter, we use the conversations.open to start a one-on-one conversation or a group conversation and use its ID to send messages.

Request parameters

Some important query parameters for the conversations.open endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

channel

string

optional

This parameter specifies the channel to which the message will be posted. It can be a public channel, a private group, or an IM channel (direct message). The value for this parameter can either be an encoded ID or a name of a channel.

prevent_creation

boolean

optional

This prevents the creation of a direct message or a multi-person direct message. It is used to see if there is an existing dm or mpdm.

return_im

boolean

optional

This indicates that we want the full IM channel definition in the response.

users

string

optional

This provides a list of user IDs.

Let’s call the conversations.open endpoint. Click the “Run” button to receive a direct message from the application.

Press + to interact
import fetch from "node-fetch";
const url = "https://slack.com/api/conversations.open";
const headerParameters = {
  Authorization: "Bearer {{TOKEN}}",
  "Content-Type": "application/json; charset=UTF-8",
};
const bodyParameters = JSON.stringify({
  users: "{{USER_ID}}",
  return_im: true,
});
const options = {
  method: "POST",
  headers: headerParameters,
  body: bodyParameters,
};
async function openConversation() {
  try {
    const response = await fetch(url, options);
    // Printing the API response and retrieving the formatted JSON object
    const content = await printResponse(response);
    // Extracting the channel ID from the response
    const channelId = content["channel"]["id"];
    const message = "Direct message!";
    // Sending a direct message using the chat.postMessage endpoint
    sendMessage(channelId, message);
  } catch (error) {
    printError(error);
  }
}
openConversation();

Let’s look at the highlighted lines in the code widget shown above:

  • Lines 10–13: We specify the users parameter as a user ID and the return_im as true to get the complete IM response.
  • Line 29: We extract the channel ID from the response of the conversations.open endpoint.
  • Line 33: We post a message using the chat.postMessage endpoint.

Response fields

A successful response from the conversations.open endpoint includes a channel property containing the details of the channel that was opened.

Note: Visit this lesson to view the details of the channel object.

Leave and join a channel

To leave and join a channel, we access https://slack.com/api/conversations.leave and the https://slack.com/api/conversations.join endpoints. Once an application has done all its required tasks in a channel, we can make it leave a channel using the conversations.leave channel.

Note: An application can leave only the channels where it has joined or created the channel itself.

Request parameters

Some important query parameters for the conversations.leave endpoint are as follows:

Parameter

Type

Category

Description

token

token

required

Authentication tokens carry the required scopes that govern the usage of different Slack applications and APIs. We usually pass these tokens as an HTTP Authorization header or as a POST parameter.

channel

string

required

This parameter specifies the channel to which the message will be posted. It can be a public channel, a private group, or an IM channel (direct message). The value for this parameter can either be an encoded ID or a name of a channel.

Let’s call the conversations.leave and conversations.join endpoints. Click the “Run” button to leave the channel and then join that channel.

Press + to interact
import fetch from "node-fetch";
const headerParameters = {
  Authorization: "Bearer {{TOKEN}}",
  "Content-Type": "application/json; charset=UTF-8",
};
const bodyParameters = JSON.stringify({
  channel: "{{CHANNEL_ID_APP}}",
});
const options = {
  method: "POST",
  headers: headerParameters,
  body: bodyParameters,
};
// Defining a function to leave a channel
async function leaveConversation() {
  try {
    const url = "https://slack.com/api/conversations.leave";
    const response = await fetch(url, options);
    await printResponse(response);
  } catch (error) {
    printError(error);
  }
}
// Defining a function to join a channel
async function joinConversation() {
  try {
    const url = "https://slack.com/api/conversations.join";
    const response = await fetch(url, options);
    await printResponse(response);
  } catch (error) {
    printError(error);
  }
}
// Defining an async function to call the leaving and joining functions
async function leaveAndJoin() {
  await leaveConversation();
  await joinConversation();
}
leaveAndJoin();

Let’s look at the highlighted lines in the code widget shown above:

  • Lines 8–10: We specify the request body, including the channel parameter from which the application will leave.
  • Line 22: We call the conversations.leave endpoint.
  • Line 33: We use the same channel ID specified on line 9 to join the channel again using the conversations.join endpoint.

Response fields

The response from the conversations.leave endpoint includes only the ok property, whereas the conversations.join endpoint also returns the details of the joined channel.

Note: Visit this lesson to view the details of the channel object.