Developer Docs | Kommunicate

Developer Docs | Kommunicate

  • Try For Free
  • Docs

›Platform APIs

Web

  • Installation
  • CMS Installation
  • Authentication
  • Conversation
  • Conversation Assignment
  • Customization
  • Localization
  • Logout
  • Troubleshooting

Android

  • Installation
  • Authentication
  • Push Notification
  • Conversation
  • Customization
  • Localization
  • Logout
  • Migration
  • Troubleshooting

iOS

  • Installation
  • Authentication
  • Push Notification
  • Conversation
  • Customization
  • Localization
  • Logout
  • Troubleshooting

React Native

  • Installation
  • Authentication
  • Push Notification
  • Conversation
  • Customization
  • Logout

Flutter

  • Installation
  • Authentication
  • Customization
  • Conversation
  • Push Notification
  • Localization
  • Troubleshooting

Ionic/Cordova/Phonegap

  • Installation
  • Authentication
  • Push Notification
  • Conversation
  • Customization
  • Localization
  • Logout
  • Resolving Errors

Ionic/Capacitor

  • Installation
  • Authentication
  • Push notification
  • Customization

Rich Messages

  • How To Use
  • Types of Rich Messages

Bots

  • Bot setup
  • Dialogflow Integration
  • Lex Integration
  • Kompose Bot Builder
  • IBM Watson Integration
  • Custom Bot Integration
  • Import Kompose Bot
  • Bot Samples

Integrations

  • Zapier
  • WhatsApp
  • WhatsApp 360Dialog
  • WhatsApp Twilio
  • WhatsApp Cloud API

Platform APIs

  • Authentication
  • Endpoints

Dashboard Features

  • Analytics
  • Conversations
  • Users
  • Bot Integration
  • Helpcenter
  • Settings

Configuration

  • Email Fallback
  • Webhooks
  • Access Token URL

Endpoints

Note: All endpoints are relative to the base url.

Create a conversation

You need to create a conversation before you can send a message to an agent/bot. This API allow you to create a new conversation. you can pass the user/agent/bot list in groupMemberList parameter. By default, Kommunicate applies the conversation rules on the newly created conversation. It means apart from the agent/bots you have passed in groupMemberList parameter, configured bot/agents from 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

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

Createconversation

parameterdatatyperequired/optionaldescription
groupNameStringRequiredThis parameter determine the group/conversation title name. It works same as the conversationTitle property in installation script
clientGroupIdNumberoptionalYou 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.
groupMemberListArray of StringRequiredThis 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.
metadataObject (Key-value pairs)optionalYou can pass configurational parameters in metadata. below is the supported parameters
metadata.SKIP_ROUTINGBooleanoptionalSet 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 conversation will be assigned to no one
metadata.
CONVERSATION_ASSIGNEE
StringoptionalSet 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 userIds in and return the list of user detail object.

Request

POST /rest/ws/user/v2/detail 
Content-Type: application/json

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

Getuserdetail

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 are the list of content types which you can use: By default and with Content type (0), 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):

HTML

Dash_screenshot

You can also send Rich messages by adding a valid JSON in metadata field. The metadata accepts the key-value pair as string. The payload object in the rich message should be converted into string before adding it into request payload. Below is the example of 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",
        "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

sendmessage

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

changeconversation

Update User Details

This API can only update a user's details. To update human agent's detail please contact to 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

Updateuserdetails

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 bot from conversation.

Example

changeconversationassignee

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

}
← AuthenticationAnalytics →
  • Create a conversation
  • Get user detail
  • Send Message
  • Change Conversation Status
  • Update User Details
  • Change Conversation Assignee

Ready to automate more than 80% of your customer support?

Try for Free
  • support@kommunicate.io
  • United States
    (+1) (310) 402-2374
  • India
    (+91) 974-057-0196
  • Docs
    • Web
    • Android
    • iOS
    • Ionic/Phonegap
    • React Native
    • Flutter
  • Product
    • Kompose Chatbot Builder
    • Live Chat
    • Integrations
    • Helpcenter
    • Dialogflow Integration
    • Features
    • Pricing and FAQs
    • Get Demo
  • Resources
    • Chatbots Templates
    • Blog
    • Kommunity
    • Support Metrics
    • Free SaaS Icons
    • ROI Calculator
    • Comparison
  • Company
    • About Us
    • Partner Program
    • Terms of Service
    • Privacy Policy
    • Jobs
    • SLA
    • DPA
  • Support
    • Knowledge Base
    • Docs
    • Stack Overflow
    • API Status
    • Contact Us
Software Advice Frontrunners for Live Chat Mar-22crozdesk badgeCapterra Shortlist for Live Chat Mar-22GetApp Category Leaders for Live Chat Mar-22GDPR compliant - GDPR Copy 12Created with Sketch.COMPLIANTG2 reviews badge
Copyright © 2023 Kommunicate.io