Cloud Services

ModernOps configuration

ChatOps APIs
Published On May 16, 2024 - 1:59 PM

ChatOps APIs

Learn how to manage ChatOps in Kyndryl Modern Operations Applications, and what items can be managed through APIs.
Managing ChatOps in the Kyndryl Modern Operations Applications is done using APIs.

Managing channels

In addition to the UI, channels can also be managed using APIs. These APIs can be found in the
Developer Console
 which is available by clicking the
User
 icon and selecting
Developer Console
. Select
Common Discovery
 for
Application
 and
Chatops
 for
Service
.
You can use the APIs from this page. Click
Try it out
, enter the parameters and body, and then click
Execute
.

Creating a channel

Create a channel using the following API:
  • Method:
     POST
  • API:
     /discovery/api/chatops/v1/channel
  • Headers:
Name
Required
Description
Type
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Authorization
Yes
User bearer token or service token
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API
string
Tenant-UUID
No
Unique ID for the tenant
string
  • Body:
     The channel metadata that is used to create a channel in application/json format as shown in the following example. The “category” is used to indicate the severity and therefore which channel in Microsoft Teams. It can be left out if you are using Slack. 
    {
"name": "string",
"description": "string",
"accountId": "string",
“category”: “string”,
"message": {
  "header": "string",
  "body": "string",
  "richText": [ <for Microsoft Teams, this must be string type containing rich text>
    {}
  ]
},
"referenceData": {}
}

Updating a channel

Update an existing channel using this API.
Channels in Microsoft Teams cannot be updated.
  • Method:
     PUT
  • API:
     /channel/{id}
  • Parameters:
Name
Required
Description
Type
Id
Yes
The unique ID of the channel
string
Authorization
Yes
User bearer token or service token
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API
string
Tenant-UUID
No
Unique ID for the tenant
string
  • Body:
     The channel metadata that is used to update the channel in application/json format as shown in the following example: 
    {
"name": "string",
"description": "string",
"status": "ACTIVE",
"message": {
  "header": "string",
  "body": "string",
  "richText": [ <for Microsoft Teams, this must be string type containing rich text>
    {}
  ]
}
}

Archiving a channel

Archive an existing channel using this API.
Channels in Microsoft Teams cannot be archived.
  • Method:
     DELETE
  • API:
     /channel/{id}
  • Parameters:
Name
Required
Description
Type
Id
Yes
The unique ID of the channel
string
Authorization
Yes
User bearer token or service token
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API
string
Tenant-UUID
No
Unique ID for the tenant
string

Managing bots

In addition to channels, bots can also be managed using APIs. These APIs can be found in the
Developer Console
 which is available by clicking the
User
icon and selecting
Developer Console
. Select
Common Discovery
 for
Application
 and
Chatops
 for
Service
.
You can use the APIs from this page. Click
Try it out
, enter the parameters and body, and then click
Execute
.

Registering a bot

Use the following API to register a bot. This is required to determine which collaboration tool to use.
For an ITSM use case, a bot is automatically registered with the default metadata.
  • Method:
     POST
  • API:
     /discovery/api/chatops/v1/bot
  • Parameters:
Name
Required
Description
Type
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string
Authorization
Yes
User bearer token or service token
string
  • Body:
     Provide the details required for bot registration in application/json format as shown in this example: 
    {
"name": "demo_chatops",
"collaborationTool": "MS_TEAMS",
"channelType": "PUBLIC",
"defaultUsers": [
"[email protected]"
],
"applicationType":"AIOPS_ITSM”
}
    The parameters are as follows:
    • name:
       Provide a name for the bot.
    • collaborationTool:
       Select either SLACK or MS_TEAMS.
    • channelType:
       Can be PUBLIC or PRIVATE.
    • defaultUsers:
       Provide a list of the users who will be the owners of the channels (for Slack) or the team (for Microsoft Teams)
    • applicationType:
       Can be AIOPS_ITSM or SERVICENOW.
After you register a bot, you will receive a bot ID that can be used to retrieve and manage that bot.

Retrieving a list of bot configurations

To get a list of all bot configurations, use the following API:
  • Method:
     GET
  • API:
     /bot
  • Parameters:
Name
Required
Description
Type
Authorization
Yes
User bearer token or service token
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string

Retrieving details for a bot configuration

To get the details for a specific bot configuration, use the following API:
  • Method:
     GET
  • API:
     /bot/{id}
  • Parameters:
Name
Required
Description
Type
id
Yes
The unique ID of the bot
string
Authorization
Yes
User bearer token or service token
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string

Updating bot configuration

Use the following API to update the configuration of a bot:
  • Method:
     PUT
  • API:
     /bot/{id}
  • Parameters:
Name
Required
Description
Type
id
Yes
The unique ID of the bot
string
Authorization
Yes
User bearer token or service token
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string
  • Body:
     Provide the details to change the configuration of the bot to in application/json format as shown in this example: 
    {
"name": "string",
"collaborationTool": "SLACK",
"channelType": "PRIVATE",
"callbackURL": "string",
"callbackHeaders": [
  {}
],
"defaultUsers": [
  "[email protected]"
],
"prefixChannelName": "string",
"isIndexChannelRequired": true
}

Retrieving a list of provider accounts

To retrieve a list of provider accounts, use the following API. X-Bot-Id is the required header for Microsoft Teams generated when you registered your bot. The ConnectionID in the output will be used as the AccountID.
  • Method:
     GET
  • API:
     /discovery/api/chatops/v1/accounts
  • Parameters:
Name
Required
Description
Type
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Authorization
Yes
User bearer token or service token
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API. This header identifies which collaboration tool the account is associated with.
string
Tenant-UUID
No
Unique ID for the tenant
string

Adding members to a channel

To add members to a channel, using the following API:
  • Method:
     POST
  • API:
     /discovery/api/chatops/v1/channel/<channelId>/members
  • Parameters:
Name
Required
Description
Type
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Authorization
Yes
User bearer token or service token
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API
string
Tenant-UUID
No
Unique ID for the tenant
string
  • Body:
     List all member emails that you want to add in application/json format as shown in the following example: 
    {
"conversationId": EXAMPLEID.34.56
"emails":  [
"[email protected]",
“[email protected]”
]

Managing messages

Messages can be managed using APIs as follows:

Posting a message to a channel

To add post to a channel, use the following API:
  • Method:
     POST
  • API:
     /discovery/api/chatops/v1/channel/<channelId>/message
  • Parameters:
Name
Required
Description
Type
channelId
Yes
The ID of the channel
string
Authorization
Yes
User bearer token or service token
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API
string
Tenant-UUID
No
Unique ID for the tenant
string
  • Body:
     Provide the payload for the message in application/json format as shown in the following example. The conversationId is used for Microsoft Teams only, and identifies the conversation within the severity channel. 
    {
"header": "string",
"body": "string",
"richText": [ <for Microsoft Teams, this must be string type containing rich text>
  {}
]
"conversationId": “string”
}

Updating a message

To edit an existing message, use the following API:
  • Method:
     PUT
  • API:
     /discovery/api/chatops/v1/channel/{channelId}/message/{messageId}
Name
Required
Description
Type
channelId
Yes
The unique ID of the channel
string
messageId
Yes
For Microsoft Teams, the unique ID of the conversation
string
Request-Id
Yes
Any unique identifier for the request (UUID)
string
Authorization
Yes
User bearer token or service token
string
Content-Type
Yes
Application/json
string
X-Bot-Id
Yes for Teams, No for Slack
A bot registration ID returned from register bot API
string
Tenant-UUID
No
Unique ID for the tenant
string
  • Body:
     Provide the payload for the message in application/json format as shown in the following example: 
    {
"header": "string",
"body": "string",
"richText": [ <for Microsoft Teams, this must be string type containing rich text>
  {}
],
"conversationId ": “string”
}
Do you have two minutes for a quick survey?
Take Survey