Connect channels for a requester Beta

In this tutorial you connect a Slack channel and a Microsoft Teams channel for an employee who asked for it, as a helpdesk tool does. You use an API key that acts as Conclude, so each step runs with the employee’s access.

Before you start

You need:

• An API key that acts as Conclude, with the scopes org:read and connections:readwrite. See Issue an API key.
• The Slack user ID of the employee, such as U07ABCDEF12. A helpdesk tool usually gets it from the request.
• Conclude in both channels if they are private. A key that acts as Conclude only reaches private channels that Conclude was added to.

The examples use curl and keep values in shell variables.

Step 1: Get a token for the employee

Ask for a token with the employee as its subject. The token then acts for the employee.

curl https://api.conclude.io/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d subject=U07ABCDEF12

Keep the access_token from the response in $ACCESS_TOKEN. It lasts one hour. If the employee has no active account in your organization, the request fails with invalid_request.

Check whom the token acts for:

curl https://api.conclude.io/v1/apiKey -H "Authorization: Bearer $ACCESS_TOKEN"

The actsFor field names the employee.

Step 2: Find the workspaces

A channel name can exist in more than one workspace. Get your workspaces, so that you can narrow the search.

curl https://api.conclude.io/v1/organization -H "Authorization: Bearer $ACCESS_TOKEN"

Each workspace has a sysID. That is the Slack workspace ID or the Microsoft Teams tenant ID.

Step 3: Find the two channels

Look up the Slack channel by name in the Slack workspace:

curl -G https://api.conclude.io/v1/findChannel \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "name=it-help" \
  --data-urlencode "sysTeamID=T04ABCDEF12"

Then look up the Teams channel. If the request names the Teams channel by its ID, search with sysChannelID:

curl -G https://api.conclude.io/v1/findChannel \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "sysChannelID=19:a1b2c3@thread.tacv2"

Check each result before you go on:

• An empty list means the employee can’t access the channel, or it doesn’t exist.
• More than one result means the name exists in several teams. Ask which one, or add sysTeamID.
• connected: true means the channel is already in a connection. A channel can be in only one.

Keep the two id values, such as C-6e8g0i2k and C-9i1k3m5o.

Step 4: Create the connection

curl https://api.conclude.io/v1/connections \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "channel", "endpoints": [{"channelID": "C-6e8g0i2k"}, {"channelID": "C-9i1k3m5o"}]}'

The response is the new connection. Keep its id, such as Y-7f9h1j3l. Messages now sync between the two channels.

Tell the employee what went wrong when the request fails:

Errors and limits lists every code.

Step 5: Check the connection

curl https://api.conclude.io/v1/connections/Y-7f9h1j3l -H "Authorization: Bearer $ACCESS_TOKEN"

Each endpoint has a status. A new endpoint is ok until Conclude first checks it. If a status shows a problem later, Status says what to do. After you fix the cause, repair the connection:

curl -X POST https://api.conclude.io/v1/connections/Y-7f9h1j3l/repair \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step 6: Change a setting

By default, posts from other apps’ bots don’t sync. To sync the bot posts from the Slack channel, change the settings of its endpoint:

curl -X PUT https://api.conclude.io/v1/connections/Y-7f9h1j3l/endpoints/C-6e8g0i2k/settings \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"syncBotMessages": true}'

This request replaces all of the endpoint’s settings. Send every setting that you want to keep. See Endpoint settings.

Step 7: Remove the connection

When the employee no longer needs the connection, delete it:

curl -X DELETE https://api.conclude.io/v1/connections/Y-7f9h1j3l \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The channels stop syncing. Their messages stay where they are.

Next steps

• Connections describes every request for connections.
• Keys and tokens explains what a key that acts as Conclude can reach.
• Audit log shows how to read the changes your tool made.