Chat API Docs

Introduction to the Chat API

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can begin making requests to the Chat API endpoints listed below. Here are the supported services, listed with service identifiers:

Chat Services
- Slack and Slack Enterprise Grid: slack
- Microsoft Teams: ms_teams

The Chat API includes the following object types:

message
conversation

Each object type is documented below, with its standard Kloudless attributes listed.

Conversation

Conversations are represented as objects that contain a list of Message objects. A Conversation may represent a chat channel, group/private message, or similar set of messages shared between users. A Conversation object has the following attributes:

id Unique identifier for the Conversation
private A boolean indicating whether this conversation is private.
name Conversation name
created ISO 8601 timestamp indicating when the object was created
members List of user IDs
type Type of object. Always conversation
raw Underlying object retrieved from the service.
api Always messaging
href The absolute URL to get the object’s metadata.

Service specific notes:

slack admin accounts optimize for org-wide access to data using the Discovery API and only permit listing conversations. Other CRUD operations require non-admin slack accounts instead.
ms_teams admin accounts do not list member-to-member private conversations; normal accounts cannot list conversation messages. Please refer to the connector guide for details.

List Conversations

list conversationsGET /accounts/{account_id}/messaging/conversations{?page_size,page}

The response contains the following information:

count Number of objects on this page
page Page identifier
next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.
objects List of Conversation objects
type Always object_list
api Always messaging

Parameters
page_size
number (optional) Default: 10
Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "total": 1,
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "name": "",
      "api": "messaging",
      "members": [
        {
          "type": "user",
          "api": "team",
          "id": "uNjgxYjM2NWVjMGE4MDE2NDAwMGZiMGIwNTg1NGEwY2Q=",
          "name": "Vinod Chandru",
          "email": "vinod@kloudless.com"
        },
        {
          "type": "user",
          "api": "team",
          "id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
          "name": "David Yu",
          "email": "david@kloudless.com"
        }
      ],
      "created": "2017-01-26T23:48:36Z",
      "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
      "private": true,
      "type": "conversation",
      "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
      "raw": {
        "object": {
          "is_general": false,
          "name_normalized": "random",
          "is_channel": true
        }
      }
    }
  ],
  "type": "object_list",
  "api": "messaging"
}

Create a Conversation

create a conversationPOST /accounts/{account_id}/messaging/conversations

To create a Conversation, perform a POST request with a JSON object with the following attributes:

private A boolean indicating whether this conversation is private.
name Conversation name
members List of user ID objects

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/messaging/conversations' \
    -XPOST -d '{
        "name": "",
        "private": true,
        "members": [
            {"id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc="},
            {"id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="}
        ]
    }'

Some notes:

slack does not currently support the members property when creating Conversation objects.

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "name": "",
  "private": true,
  "members": [
    {
      "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc="
    },
    {
      "id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="
    }
  ]
}

Response 201Toggle

Headers

Content-Type: application/json

Body

{
  "name": "",
  "api": "messaging",
  "members": [
    {
      "type": "user",
      "api": "team",
      "id": "uNjgxYjM2NWVjMGE4MDE2NDAwMGZiMGIwNTg1NGEwY2Q=",
      "name": "Vinod Chandru",
      "email": "vinod@kloudless.com"
    },
    {
      "type": "user",
      "api": "team",
      "id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
      "name": "David Yu",
      "email": "david@kloudless.com"
    }
  ],
  "created": "2017-01-26T23:48:36Z",
  "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
  "private": true,
  "type": "conversation",
  "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
  "raw": {
    "object": {
      "is_general": false,
      "name_normalized": "random",
      "is_channel": true
    }
  }
}

Retrieve a Conversation

retrieve a ConversationGET /accounts/{account_id}/messaging/conversations/{conversation_id}

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "name": "",
  "api": "messaging",
  "members": [
    {
      "type": "user",
      "api": "team",
      "id": "uNjgxYjM2NWVjMGE4MDE2NDAwMGZiMGIwNTg1NGEwY2Q=",
      "name": "Vinod Chandru",
      "email": "vinod@kloudless.com"
    },
    {
      "type": "user",
      "api": "team",
      "id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
      "name": "David Yu",
      "email": "david@kloudless.com"
    }
  ],
  "created": "2017-01-26T23:48:36Z",
  "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
  "private": true,
  "type": "conversation",
  "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
  "raw": {
    "object": {
      "is_general": false,
      "name_normalized": "random",
      "is_channel": true
    }
  }
}

Update a Conversation

update a conversationPATCH /accounts/{account_id}/messaging/conversations/{conversation_id}

To update a Conversation, create a JSON object with any of the following properties:

name New Conversation name
members List of user ID objects. Add new users to include them in this Conversation or remove users to remove them from the Conversation.

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "members": [
            {"id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc="},
            {"id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="}
        ]
    }' \
    'https://api.kloudless.com/v1/accounts/123/messaging/conversations/FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR

Some notes:

slack currently does not support the members property when updating Conversation objects.

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "name": "",
  "private": true,
  "members": [
    {
      "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc="
    },
    {
      "id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="
    }
  ]
}

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "name": "",
  "api": "messaging",
  "members": [
    {
      "type": "user",
      "api": "team",
      "id": "uNjgxYjM2NWVjMGE4MDE2NDAwMGZiMGIwNTg1NGEwY2Q=",
      "name": "Vinod Chandru",
      "email": "vinod@kloudless.com"
    },
    {
      "type": "user",
      "api": "team",
      "id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
      "name": "David Yu",
      "email": "david@kloudless.com"
    }
  ],
  "created": "2017-01-26T23:48:36Z",
  "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
  "private": true,
  "type": "conversation",
  "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
  "raw": {
    "object": {
      "is_general": false,
      "name_normalized": "random",
      "is_channel": true
    }
  }
}

Delete a Conversation

delete a conversationDELETE /accounts/{account_id}/messaging/conversations/{conversation_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/messaging/conversations/FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR'

Response 204

List Conversation Members

list the members of a conversationGET /accounts/{account_id}/messaging/conversations/{conversation_id}/members{?page_size,page}

The response contains the following information:

count Number of objects on this page
page Page identifier
next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.
objects List of User objects
type Always object_list
api Always messaging

Some notes:

slack only returns the conversation members’ id.

Parameters
page_size
number (optional) Default: 10
Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

Response 200Toggle

Headers

Content-Type: application/json

Body

{
  "count": 1,
  "next_page": null,
  "page": "1",
  "objects": [
    {
      "id": "u4806226",
      "id_type": "default",
      "name": "Test User",
      "email": "user@test.com",
      "calendar_id": "fdXNlckB0ZXN0LmNvbQ==",
      "type": "user",
      "api": "team",
      "ids": {
        "default": "u4806226",
        "team": "t3141592"
      },
      "href": "https://api.kloudless.com/v1/accounts/123/team/users/u4806226"
    }
  ],
  "type": "object_list",
  "api": "messaging"
}

Messages

A Message object represents metadata on an individual message within a Conversation. A Message has the following attributes:

id Unique identifier for the Message
conversation_id Unique identifier of a conversation the message belongs to
sender The user sent this message
created ISO 8601 timestamp indicating when the message was created
text The message body
parent Unique identifier of the message to be replied
type Type of object. Always message
raw Underlying object retrieved from the service.
api Always messaging
href The absolute URL to get the object’s metadata.

Service specific notes:

slack admin accounts optimize for org-wide access to data using the Discovery API and only permit listing messages as well as updating or deleting existing messages. Message creation or metadata retrieval require connecting non-admin slack accounts instead.

List Messages

list messages of a conversationGET /accounts/{account_id}/messaging/conversations/{conversation_id}/messages{?page_size,page}

The response contains the following information:

count Number of objects on this page
page Page identifier
next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.
objects List of Message objects
type Always object_list
api Always messaging

Parameters
page_size
number (optional) Default: 10
Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

page
string (optional)
Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

Response 200Toggle

Headers

Content-Type: application/json

Body

{
    "total": 2,
    "count": 2,
    "page": 1,
    "next_page": null,
    "objects": [
                                {
                "api": "messaging",
                "sender": {
                    "type": "user",
                    "api": "team",
                    "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
                    "name": "Vinod Chandru",
                    "email": "vinod@kloudless.com"
                },
                "created": "2017-07-18T00:02:01Z",
                "text": "hello, can you send the doc by today?",
                "id": "FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
                "parent": "",
                "type": "message",
                "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
                "raw": {
                    "object": {
                        "attachments": [{
                            "fallback": "text",
                            "id": 1,
                            "pretext": "Pre text",
                            "text": "text"
                        }],
                    }
                }
            },
        {
            "api": "messaging",
            "sender": {
                "type": "user",
                "api": "team",
                "id": "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
                "name": "David Yu",
                "email": "david@kloudless.com"
            },
            "created": "2017-07-18T00:03:01Z",
            "text": "No problem!",
            "id": "FBanuaEjDQnVDNmpOllqJzLKJ=",
            "parent": "",
            "type": "message",
            "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBanuaEjDQnVDNmpOllqJzLKJ="
        }
    ],
    "type": "object_list",
    "api": "messaging"
}

Create a Message

create a messagePOST /accounts/{account_id}/messaging/conversations/{conversation_id}/messages

To create a Message, perform a POST request with a JSON object with the following attributes:

sender The user that sent this Message
text The Message body
parent Unique identifier of the Message this Message was in response to. Required if a Message is to be considered a response in a thread.
raw Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages' \
    -XPOST -d '{
        "text": "hello, can you send the doc by today?",
        "sender": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "parent": "",
        "raw": {
            "object": {
                "attachments": [{
                    "pretext": "Pre text",
                    "text": "text"
                }]
            }
        }
    }'

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "text": "hello, can you send the doc by today?",
  "sender": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
  "parent": ""
}

Response 201Toggle

Headers

Content-Type: application/json

Body

{
        "api": "messaging",
        "sender": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
        },
        "created": "2017-07-18T00:02:01Z",
        "text": "hello, can you send the doc by today?",
        "id": "FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
        "parent": "",
        "type": "message",
        "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
        "raw": {
            "object": {
                "attachments": [{
                    "fallback": "text",
                    "id": 1,
                    "pretext": "Pre text",
                    "text": "text"
                }],
            }
        }
    }

Retrieve a Message

retrieve a MessageGET /accounts/{account_id}/messaging/conversations/{conversation_id}/messages/{message_id}

Response 200Toggle

Headers

Content-Type: application/json

Body

{
        "api": "messaging",
        "sender": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
        },
        "created": "2017-07-18T00:02:01Z",
        "text": "hello, can you send the doc by today?",
        "id": "FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
        "parent": "",
        "type": "message",
        "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
        "raw": {
            "object": {
                "attachments": [{
                    "fallback": "text",
                    "id": 1,
                    "pretext": "Pre text",
                    "text": "text"
                }],
            }
        }
    }

Update a Message

update a messagePATCH /accounts/{account_id}/messaging/conversations/{conversation_id}/messages/{message_id}

To update a Message, create a JSON object with any of the following properties:

text The Message body

The new Message object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "text": "hello, can you send the doc by today?"
    }' \
    'https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBtuaEjDQnVDNmpOllqJzhmmkDzOK='

RequestToggle

Headers

Authorization: Bearer [TOKEN]
Content-Type: application/json

Body

{
  "text": "hello, can you send the doc by today?"
}

Response 200Toggle

Headers

Content-Type: application/json

Body

{
        "api": "messaging",
        "sender": {
            "type": "user",
            "api": "team",
            "id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
            "name": "Vinod Chandru",
            "email": "vinod@kloudless.com"
        },
        "created": "2017-07-18T00:02:01Z",
        "text": "hello, can you send the doc by today?",
        "id": "FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
        "parent": "",
        "type": "message",
        "href": "https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBtuaEjDQnVDNmpOllqJzhmmkDzOK=",
        "raw": {
            "object": {
                "attachments": [{
                    "fallback": "text",
                    "id": 1,
                    "pretext": "Pre text",
                    "text": "text"
                }],
            }
        }
    }

Delete a Message

delete a messageDELETE /accounts/{account_id}/messaging/conversations/{conversation_id}/messages/{message_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/123/messaging/conversations/FGx9Vhs7YaPX-jYbGdPAwfA==/messages/FBtuaEjDQnVDNmpOllqJzhmmkDzOK='

Response 204

Files

Check out the Storage API for information on files shared in Slack. Start by listing all files in the root folder using the Retrieve Folder Contents endpoint.

Note that slack admin accounts prioritize org-wide access to data via the Discovery API, so arbitrary file uploads are not permitted. However, retrieving and listing metadata, as well as downloading and deleting files, are supported.

Activity Monitoring

Track new Conversation and Message activity via the Activity API endpoint.

To track org-wide data in Slack Enterprise Grid, visit our v2 Audit Activity API instead.

Activity API required: These endpoints require your Kloudless subscription to include access to the Activity API.

Note that slack admin accounts prioritize providiing org-wide activity, with granularity to the conversation level. To be aware of Message activity, either periodically list new Messages in each Conversation, or use a separate non-admin account to monitor activity in Conversations that account has access to.

Users and Groups

The Team API provides information on users and groups.