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

  • api Always messaging

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": "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
                        "name": "David Yu",
                        "email": "david@kloudless.com"
                    }
                ]
                "created": "2017-01-26T23:48:36Z",
                "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
                "private": True,
                "type": "conversation"
            }
        ],
        "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 IDs

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": ["uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=", "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="]
    }'
  • RequestToggle
  • Headers

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

    Body

    {
      "name": "",
      "private": true,
      "members": [
        "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="
      ]
    }
  • 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": "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
                    "name": "David Yu",
                    "email": "david@kloudless.com"
                }
            ]
            "created": "2017-01-26T23:48:36Z",
            "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
            "private": true,
            "type": "conversation"
        }

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": "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
                    "name": "David Yu",
                    "email": "david@kloudless.com"
                }
            ]
            "created": "2017-01-26T23:48:36Z",
            "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
            "private": true,
            "type": "conversation"
        }

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 IDs. 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": ["uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc="]
    }' \
    'https://api.kloudless.com/v1/accounts/15/messaging/conversations/FctP2kuVA1Fr8BHwNlAVMVySl6wfF-oV9y304Ymr8iCcy2xGW8XYdOJN6TxzlpFuY
  • RequestToggle
  • Headers

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

    Body

    {
      "name": "",
      "private": true,
      "members": [
        "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND="
      ]
    }
  • 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": "Nj1QYNgijTNjNGuM42GwEVAYMGZMIE2w2gGxMMEWwDND=",
                    "name": "David Yu",
                    "email": "david@kloudless.com"
                }
            ]
            "created": "2017-01-26T23:48:36Z",
            "id": "FEQ3vnFTmdOF-IlGh8pcdtl9acrGLR03cmCBTTsgKHHHxItMiBoWkldC6O_uyV7PR",
            "private": true,
            "type": "conversation"
        }

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/accounts/34/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

  • api Always messaging

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": "0",
          "conversation_id": "1",
          "parent": "",
          "type": "message"
        },
        {
          "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": "1",
          "conversation_id": "1",
          "parent": "",
          "type": "message"
        }
      ],
      "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.

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/456/messages' \
    -XPOST -d '{
        "conversation_id": "1",
        "text": "hello, can you send the doc by today?",
        "sender": "uNTEzNzE1M2NjNjExMjI3YzAwMGJiZDFiZDhjZDIwMDc=",
        "parent": ""
    }'
  • RequestToggle
  • Headers

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

    Body

    {
      "conversation_id": "1",
      "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": "0",
      "conversation_id": "1",
      "parent": "",
      "type": "message"
    }

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": "0",
      "conversation_id": "1",
      "parent": "",
      "type": "message"
    }

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? Thanks!"
    }' \
    'https://api.kloudless.com/v1/accounts/15/messaging/conversation/20/messages/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl
  • 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": "0",
      "conversation_id": "1",
      "parent": "",
      "type": "message"
    }

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/accounts/34/messaging/conversation/56/messages/Fc1GyHgRrEKK0zzPXPyj1MB2UgJlb3Bx72LJ-npTpEWHy4sZmnXUiX3pY-tDyHWwl'
  • 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.

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.