Reference

Connections Beta

On this page

A connection syncs messages between channels, usually a Slack channel and a Microsoft Teams channel. Each channel in a connection is an endpoint. The requests on this page list, create, repair and remove connections, and change the settings of each side.

The API creates Internal connections, between channels of your own organization. External and Bridge connections start with an invitation in the Dashboard. The API can read them, change your side, repair them and remove them.

Who can change connections

Reading needs the scope connections:read. Every change needs connections:readwrite.

The person the token acts for needs a permission from Admin console > Account > Roles & permissions :

ConnectionPermission
InternalConnect channels
ExternalConnect external channels
BridgeManage bridges, or admin rights on that bridge

For each channel, the person must be a full member of its workspace or team. Guests don’t count. For a private channel, the person must also be a member of the channel. A connection is visible when the person can access at least one of its endpoints.

A key that acts as Conclude follows extra rules:

  • It holds the permissions above through its scopes
  • It only reaches channels that Conclude reaches. It can’t change or remove an endpoint whose channel Conclude doesn’t reach. Conclude answers not_found
  • Every change needs a token with a subject. Without one, Conclude answers subject_required

On an External or Bridge connection, you can change and remove only your own organization’s endpoints.

The connection object

{
  "id": "Y-7f9h1j3l",
  "type": "channel",
  "settings": {},
  "endpoints": [
    {
      "orgID": "O-2a4c6e8g",
      "teamID": "T-4c6e8g0i",
      "channelID": "C-6e8g0i2k",
      "sysChannelID": "C07ABCDEF12",
      "status": "ok",
      "settings": {
        "syncBotMessages": true
      },
      "created": "2026-10-27T14:03:12.52Z",
      "teamName": "Example",
      "channelName": "it-help",
      "platform": "slack",
      "url": "slack://channel?team=T04ABCDEF12&id=C07ABCDEF12"
    },
    {
      "orgID": "O-2a4c6e8g",
      "teamID": "T-8h0j2l4n",
      "channelID": "C-9i1k3m5o",
      "sysChannelID": "19:a1b2c3@thread.tacv2",
      "status": "ok",
      "settings": {},
      "created": "2026-10-27T14:03:12.52Z",
      "teamName": "IT",
      "channelName": "Help",
      "platform": "teams",
      "url": "https://teams.microsoft.com/l/channel/19:a1b2c3@thread.tacv2"
    }
  ],
  "lastActivity": "2026-10-27T15:20:00Z",
  "created": "2026-10-27T14:03:12.52Z",
  "modified": "2026-10-27T14:03:12.52Z"
}
FieldTypeDescription
idstringThe connection’s ID.
typestringchannel for an Internal connection, external or bridge.
bridgeIDstringThe bridge’s ID, for a connection that belongs to a bridge.
settingsobjectReserved for settings of the whole connection. It is always empty today.
endpointsarrayThe connection’s endpoints. Slack comes before Microsoft Teams, then they are sorted by team and channel name.
lastActivitytimeWhen a message last synced, to the minute.
createdtimeWhen the connection was created.
modifiedtimeWhen the connection was last changed.

The endpoint object

FieldTypeDescription
orgIDstringThe organization the channel belongs to. On an External or Bridge connection, it can be another organization.
teamIDstringThe channel’s team or workspace.
channelIDstringThe channel’s Conclude ID. The paths below take it as {channel}.
sysChannelIDstringThe Slack or Microsoft Teams channel ID.
platformstringslack or teams.
statusstringThe endpoint’s health. See Status.
disabledbooleantrue when Conclude stopped syncing this endpoint. See Status.
warningstringlateDelivery when Microsoft Teams delivers the channel’s messages late. See Status.
settingsobjectThe endpoint’s settings.
createdtimeWhen the channel joined the connection.
teamNamestringThe team’s or workspace’s name.
channelNamestringThe channel’s name.
urlstringA link that opens the channel in Slack or Microsoft Teams. A Slack link opens the Slack app.
appInfoobjectThe Conclude app installed in the channel, with icon, name and label. Left out when there is none.
orgNamestringExternal connections only. The other organization’s name.
contactstringExternal connections only. The name of the endpoint’s owner.
emailstringExternal connections only. The email address of the endpoint’s owner.

Endpoint settings

Each endpoint has its own settings. Most of them decide what this side sends to the others.

FieldTypeDescription
ownerstringThe user ID of the person responsible for this side. It must be a user with an active account in your organization.
inviterbooleantrue on the side that sent the External invitation. Only the invitation sets it. Conclude ignores it in requests.
syncBotMessagesbooleantrue to sync posts from other apps’ bots on this side. Conclude agents always sync. The default is false.
syncSystemMessagesbooleantrue to sync system messages from this side, such as notices that someone joined. The default is false.
attachmentPolicystringWhat happens to files sent from this side. copy copies them, useReferences sends a link, and ignore leaves them out. Empty uses your organization’s policy.
attachmentPolicyForImagesstringThe same for images. Empty makes images follow the file policy.
translatestringA language code, such as de or fr. Messages that arrive in this channel are translated into it. Empty turns translation off.

The two attachment policies take effect only when an admin has turned on Allow channel-level overrides. Otherwise the organization’s policy applies. See File and image sharing.

Status

Each endpoint has a status. Conclude checks connections regularly and updates it.

StatusMeaningWhat to do
okThe endpoint syncs. A new endpoint is ok until Conclude first checks it.Nothing.
noBotSlack. Conclude is not in the channel.Add Conclude to the channel, then repair the connection.
noAuthSlack: Conclude can no longer reach the channel, for example because it was made private. Microsoft Teams: no one who signed in to Conclude can see the channel.Slack: add Conclude to the channel. Microsoft Teams: have a member of the channel sign in to Conclude. Then repair the connection.
noSubMicrosoft Teams. Conclude doesn’t receive the channel’s messages.Repair the connection.
expiredSubMicrosoft Teams. Conclude’s subscription to the channel’s messages has expired.Repair the connection.
deactivatedThe channel was archived or deleted.Remove the endpoint.
teamDeactivatedConclude was removed from the workspace, or the workspace is suspended.Install Conclude in the workspace again.
connectionErrorConclude doesn’t treat the channel as connected.Contact support.
pausedAn admin paused the connection’s bridge.Resume the bridge in the Dashboard.
corruptThe connection has fewer than two endpoints.Delete the connection.

When an endpoint stays noBot, noAuth, noSub or expiredSub for seven days, Conclude stops syncing it and sets disabled to true. For corrupt, that happens after two hours. The other statuses never disable an endpoint. A disabled endpoint neither sends nor receives messages. It turns itself back on once Conclude finds it healthy.

An endpoint in your organization that still syncs can carry a warning. lateDelivery means Microsoft Teams delivered three of the channel’s messages late within a week. Add the Conclude app to the team or chat, so that messages arrive without waiting for Microsoft’s notifications. If Teams refuses, ask your Teams administrator to allow the Conclude app.

List connections

GET /v1/connections · scope connections:read

Returns a page of the connections with an endpoint in your organization that the token can see, newest first by when they were created. Chats are on the Chats page.

curl -G https://api.conclude.io/v1/connections \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "limit=100"
FieldTypeDescription
connectionsarrayThe connection objects on this page.
nextPositionstringThe position of the next page. It is empty on the last page.
StatusCodeWhen
400invalid_requestlimit is not a positive number, or position is not one Conclude returned. param names the parameter.

Get a connection

GET /v1/connections/{connection} · scope connections:read

Returns one connection object.

curl https://api.conclude.io/v1/connections/Y-7f9h1j3l -H "Authorization: Bearer $ACCESS_TOKEN"
StatusCodeWhen
404not_foundThe connection doesn’t exist, has no endpoint in your organization, or the token can’t see it.

Create a connection

POST /v1/connections · scope connections:readwrite

Connects two or more channels of your organization. Conclude marks the channels as connected and starts to sync them. The audit log records connect.channel.created.

FieldTypeRequiredDescription
typestringYesAlways channel.
endpointsarrayYesTwo or more channels.
endpoints[].channelIDstringYesThe channel’s Conclude ID, from GET /v1/findChannel.
endpoints[].settingsobjectNoThe channel’s settings.
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 object.

StatusCodeWhen
400invalid_requesttype is not channel. There are fewer than two endpoints, or a channel appears twice. A channelID is empty. A setting has the wrong type, or owner is not a user in your organization. param names the field, as in endpoints.1.settings.owner.
400channel_not_connectableA channel is archived or deleted, or is not a regular channel.
403forbiddenThe person the token acts for doesn’t have the Connect channels permission.
403subject_requiredA key that acts as Conclude sent no subject.
403conclude_not_in_channelA key that acts as Conclude named a channel that Conclude doesn’t reach.
403channel_access_deniedThe person the token acts for can’t access a channel.
403plan_limitYour organization’s plan has no room for another channel connection. param is internalConnections or connections.
404not_foundA channel doesn’t exist or belongs to another organization. param names it, as in endpoints.1.channelID.
409already_connectedA channel is already in a connection.
409connections_disabledChannel connections are turned off for your organization.

Delete a connection

DELETE /v1/connections/{connection} · scope connections:readwrite

Deletes the connection and stops syncing all its channels. On an External connection, this also removes the other organization’s side. On a Bridge connection, it disconnects the channels from the bridge. The response is 200 with an empty body.

A key can delete an External or Bridge connection only when at most one of its endpoints belongs to another organization. Otherwise, remove your own endpoints.

curl -X DELETE https://api.conclude.io/v1/connections/Y-7f9h1j3l -H "Authorization: Bearer $ACCESS_TOKEN"
StatusCodeWhen
403forbiddenThe person the token acts for doesn’t have the permission for this connection. Or a key tried to delete a connection with endpoints in several other organizations.
403subject_requiredA key that acts as Conclude sent no subject.
404not_foundThe connection doesn’t exist, or the token can’t see it.

Repair a connection

POST /v1/connections/{connection}/repair · scope connections:readwrite

Checks every endpoint and fixes what Conclude can fix. It reads each channel again from Slack or Microsoft Teams. It renews Conclude’s subscriptions to the channels’ messages. In Microsoft Teams, it also adds Conclude’s integration account to a private or shared channel again. Then it checks the endpoints once more and updates their status.

The request has no body. Repair runs while you wait, so it can take several seconds. The response is the connection object with the new status of each endpoint.

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

Repair can’t fix every status. See Status for what to do. If an endpoint has been broken longer than its grace period, repair disables it, and Conclude alerts your admins.

StatusCodeWhen
403forbiddenThe person the token acts for doesn’t have the permission for this connection.
403subject_requiredA key that acts as Conclude sent no subject.
404not_foundThe connection doesn’t exist, or the token can’t see it.
503unavailableThe repair was interrupted. Try again.

Add an endpoint

POST /v1/connections/{connection}/endpoints · scope connections:readwrite

Adds a channel of your organization to an Internal connection.

FieldTypeRequiredDescription
channelIDstringYesThe channel’s Conclude ID.
settingsobjectNoThe channel’s settings.
curl https://api.conclude.io/v1/connections/Y-7f9h1j3l/endpoints \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelID": "C-0j2l4n6p"}'

The response is the connection object with the new endpoint.

StatusCodeWhen
400invalid_requestThe connection is not an Internal connection. channelID is empty. A setting has the wrong type, or owner is not a user in your organization.
400channel_not_connectableThe channel is archived or deleted, or is not a regular channel.
403forbiddenThe person the token acts for doesn’t have the Connect channels permission.
403subject_requiredA key that acts as Conclude sent no subject.
403conclude_not_in_channelA key that acts as Conclude named a channel that Conclude doesn’t reach.
403channel_access_deniedThe person the token acts for can’t access the channel.
404not_foundThe connection doesn’t exist, or the token can’t see it. The channel doesn’t exist or belongs to another organization.
409already_connectedThe channel is already in a connection.
409connections_disabledChannel connections are turned off for your organization.

Remove an endpoint

DELETE /v1/connections/{connection}/endpoints/{channel} · scope connections:readwrite

Removes a channel of your organization from the connection. {channel} is the channel’s Conclude ID.

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

When fewer than two endpoints remain, Conclude deletes the whole connection. The response is then the connection with an empty endpoints list. Removing either side of a Bridge connection disconnects both. Otherwise the response is the connection object without the removed endpoint.

StatusCodeWhen
403forbiddenThe person the token acts for doesn’t have the permission for this connection. Or the channel belongs to another organization.
403subject_requiredA key that acts as Conclude sent no subject.
404not_foundThe connection doesn’t exist, the channel is not part of it, or the token can’t see it.

Change endpoint settings

PUT /v1/connections/{connection}/endpoints/{channel}/settings · scope connections:readwrite

Replaces the settings of one of your organization’s endpoints. The body is the settings object. A field you leave out goes back to its default. Leaving out owner keeps the current owner, and inviter never changes.

To change one setting, read the connection first, change the setting and send all the settings back.

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, "translate": "de"}'

The response is the endpoint object with its new settings.

StatusCodeWhen
400invalid_requestA setting has the wrong type, or owner is not a user in your organization. param names it, as in owner.
403forbiddenThe person the token acts for doesn’t have the permission for this connection. Or the channel belongs to another organization.
403subject_requiredA key that acts as Conclude sent no subject.
404not_foundThe connection doesn’t exist, the channel is not part of it, or the token can’t see it.