Endpoints

Note: All endpoints are relative to the Base URL: https://services.kommunicate.io

Create a conversation

You need to create a conversation before you can send a message to an agent/bot. This API allows you to create a new conversation. you can pass the user/agent/bot list in groupMemberList parameter. By default, Kommunicate applies the conversation rules to the newly created conversation. It means apart from the agent/bots you have passed in groupMemberList parameter, configured bots/agents from the conversation rule section will also get added in to the conversation. You can pass the configurational parameter in metadata to customize the behavior.

To get your API Key

Go to your Kommunicate Dashboard >> ⚙️Settings >> INSTALL >> API Key

POST rest/ws/group/conversation
Content-Type: application/json
Api-Key: <"get your Api-Key from dashboard">

{
  "groupName": " group name", 
  "groupMemberList":["user-id-to-be-added-in-conversation"]
}

Example

parameter	datatype	required/optional	description
groupName	String	Required	This parameter determine the group/conversation title name. It works same as the conversationTitle property in installation script
clientGroupId	Number	optional	You can generate a unique id for every group/conversation and use it later for group operations like sending a message, fetching group detail etc. By default, Kommunicate populates this parameter.
groupMemberList	Array of String	Required	This is the list of users/agents/bots you want to add into conversations. You need to pass at least one user. Kommunicate will create the user if user is not present. By default, Conversation rules will be applied to determine the assignee.
metadata	Object (Key-value pairs)	optional	You can pass configurational parameters in metadata. below is the supported parameters
metadata.SKIP_ROUTING	Boolean	optional	Set this parameter to true, to skip the conversation rules. If you are using this parameter make sure you are setting the CONVERSATION_ASSIGNEE parameter. Otherwise, the conversation will be assigned to no one
metadata. CONVERSATION_ASSIGNEE	String	optional	Set the conversation assignee. This parameter only works with SKIP_ROUTING: true. If you are using this parameter, make sure the agent/bot id you are passing here should be present in groupMemberListparameter

Get user detail

Accepts the list of user IDs in and returns the list of user detail objects.

Request

POST /rest/ws/user/v2/detail 
Content-Type: application/json
API-key: your API key found in the Install section of the dashboard
Query Params: fetchLatestMessageTime: True

POST BODY
{
  "userIdList":["userId1","userId2"]
}

Response

[{
  "userId": "UserId1", // UserId of the user (String)
  "userName": "Display name", // Name of the user (String)
  "connected": true, // Current connected status of user, if "connected": true                                          //that means user is online (boolean)
  "lastSeenAtTime": 12345679,  // Timestamp of the last seen time of user (long)
  "createdAtTime": 148339090,         //  Timestamp of the user's creation (long)
  "imageLink": "http://image.url",    // Image url of the user
  "deactivated": false,               // user active/inactive status (boolean)
  "phoneNumber": "+912345678954",       // phone number of user
  "unreadCount": 10,                                // total unread message count
  "lastLoggedInAtTime": 1483342919147,//  Timestamp of the user's last logged in                                                                             //(long)
  "lastMessageAtTime": 1483343150550  //Timestamp of the user's last message                                                                                 //(long)
 }]

Example

Send Message

Send a message to a conversation/group. A group Id is assigned to every conversation when its created and can not be changed. If messages are received from webhook, every message will have the groupId parameter associated with them. Use this group Id to send the messages in the conversation.

POST  /rest/ws/message/v2/send 
Content-Type: application/json
POST Body:
{ 
  "groupId": "group Unique Identifier", 
  "clientGroupId": "client group id if any" // optional
  "message":"Hi John",
  "fromUserName":"userId of sender"
}

Here is the list of content types that you can use: By default and with the Content type (0), the message is sent as plain text.

DEFAULT(0) | ATTACHMENT(1) | LOCATION(2) | TEXT_HTML(3) | PRICE(4) | IMAGELINK(5) | HYPERLINK(6)

Example for HTML content type (3):

You can also send Rich messages by adding a valid JSON in the metadata field. The metadata accepts the key-value pair as a string. The payload object in the rich message should be converted into a string before adding it to the request payload. Also, we need to add a parameter skipBot (boolean type), which acts as a flag in case messages come from an agent. So when it is set to true, it will prevent the execution of the code twice. Below is an example of a request body with Rich Message (Suggested Reply):

{ 
  "groupId": "group Unique Identifier", 
  "message":"Do you want more updates?",
  "fromUserName":"userId of sender",
  "metadata":{       
       "contentType": "300",
        "templateId": "6",
        "skipBot": true, 
        "payload": "[{\"title\":\"Yes\",\"message\":\"Cool! send me more.\"},{\"title\":\"No \",\"message\":\"Don't send it to me again\"}]"  // any object should be converted into string inside metadata.
  }
}

Example

Send Attachments

curl --location 'https://services.kommunicate.io/rest/ws/message/send' \
--header 'of-user-id: Super Admin email' \
--header 'Content-Type: application/json' \
--header 'API-key: your API key found in the Install section of the dashboard' \
--data '{
        "type": 5,
        "contentType": 1,
        "message": "This is an image description",
        "groupId": "Add Conversation id",
        "metadata": {
          "skipBot": true
        },
        "key": "m4jgfy",
        "fileMeta": {
          "blobKey": "2953a1e4-5777-4952-82d1-de3729ec5585_9e82d030948ac5ba52eb67ca0b4f2b8afe48810f_KM_BUCKET_Screenshot%202024-12-10%20at%202.55.46%20PM.png", // no changes here
          "name": "ABX.png", // optional
          "size": 182025, // optional
          "contentType": "image/png",
          "thumbnailUrl": "https://repository-images.githubusercontent.com/144950190/23ec0480-2654-11ea-9ad2-fa477c4870e5", // enter image url 
          "createdAtTime": 1735049558019 // optional
        },
        "source": 1
      }'

Example

Change Conversation Status

PATCH /rest/ws/group/status/change 

Content-Type: application/json,
Of-User-Id: your userId,
Api-Key: your api key

Query params:
    groupId:"group Unique Identifier" // unique id of conversation
    status:2 // possible values {0: open, 2: close, 3:spam}
    sendNotifyMessage:false //by default value is true

Example

Update User Details

This API can only update a user's details. To update the human agent's detail please contact Kommunicate support. Of-User-Id is the user to be updated and should be passed in the request headers.

POST  /rest/ws/user/update 
Content-Type: application/json  
Of-User-Id: user_id  // user id to be updated.

POST Body:
{ 
  "email":"user email",
  "displayName":"user display name",
  "imageLink":"User profile image url",
  "metadata":{
    "key-1":"value-1" // any number of key value pairs, it will be visible to agents in dashboard.
    }
}

Example

Change Conversation Assignee

PATCH /rest/ws/group/assignee/change

Content-Type: application/json,
Of-User-Id: your userId,
Api-Key: your API key

Query params:
    groupId:"group Unique Identifier"
    assignee:"<AGENT_ID>" // Replace <AGENT_ID> with your human agent's email
    sendNotifyMessage:false //by default true
    takeOverFromBot:true // This will remove all the bots from the conversation.

Example

Change Conversation Assignee Responses

Assigned to already assigned agent

{
    "status": "success",
    "generatedAt": 1620143658894,
    "response": "already updated"
}

Assignee reached his max handling limit

{
    "status": "success",
    "generatedAt": 1620143573144,
    "response": "AGENT_IS_ALREADY_ENGAGED"
}

Wrong agent id

{
    "status": "error",
    "errorResponse": [
        {
            "errorCode": "AL-U-01",
            "description": "user not found",
            "displayMessage": "unable to process"
        }
    ],
    "generatedAt": 1620143764853
}

Wrong conversation id

{
    "status": "error",
    "errorResponse": [
        {
            "errorCode": "AL-G-01",
            "description": "group not found",
            "displayMessage": "unable to process"
        }
    ],
    "generatedAt": 1620143802170
}

Change status

{
    "status": "success",
    "generatedAt": 1620143212964,
    "response": "updated"
}

Change status if already updated

{
    "status": "success",
    "generatedAt": 1620143268723,
    "response": "already updated"
}

Wrong conversation id

{
    "status": "error",
    "errorResponse": [
        {
            "errorCode": "AL-G-01",
            "description": "group not found",
            "displayMessage": "unable to process"
        }
    ],
    "generatedAt": 1620142997609

}