Back to top

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: slack

The Messaging API has the following available 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

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

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