Introduction to the Messaging 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 perform API requests to the Messaging API endpoints listed below.

Here are the supported services, listed with service identifiers:

  • Messaging Services
    • Slack and Slack Enterprise Grid: slack

The Messaging API includes the following object types:

  • message

  • conversation

Each of these objects types is documented below, with their standard Kloudless attributes listed.


Conversation 

Conversations are represented as objects that contain a list of Message objects. A conversation 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 eDiscovery API and only permit listing conversations. Other CRUD operations require non-admin slack accounts instead.

List Conversations 

list conversationGET /accounts/{account_id}/messaging/conversation{?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. 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

    {
      "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/conversation

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/conversation' \
    -XPOST -d '{
        "name": "",
        "private": true,
        "members": [
            {"id": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc="},
            {"id": "uNj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="}
        ]
    }'

Some notes:

  • slack currently does not support members property.
  • 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 members property.
  • 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

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 eDiscovery 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. 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

    {
        "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. List all files in the root folder here.

Note that slack admin accounts prioritize org-wide access to data via the Discovery API and hence do not permit arbitrary file uploads, although retrieving and listing metadata, as well as downloading and deleting files, is supported.


Activity Monitoring 

Track new channel and message activity via the Events API endpoint.

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

Events API required: These endpoints require your Kloudless subscription to include access to the Events 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 channel, or use a separate non-admin account to monitor activity in channels that account has access to.


Users and Groups 

The Team API provides information on users and groups.