Installation

This plugin uses native UI screens and can be used for cordova, ionic and phonegap projects.

Setup

Cordova

If you are using Ionic, use the below commands to add plugin:

ionic cordova plugin add kommunicate-cordova-plugin
npm install @ionic-native/kommunicate

Capacitor

If you are using capacitor, add the plugin as below :

npm install kommunicate-cordova-plugin
npx cap sync
npm install @ionic-native/kommunicate

For iOS, you need to add Kommunicate pod dependency in CordovaPlugin Podspec file. Open the project in xcode and add the below dependency in CordovaPlugins.podspec file (Absolute path: <YourProject>/ios/capacitor-cordova-ios-plugins/CordovaPlugins.podspec) :

 s.dependency 'Kommunicate'

You can add the above dependency just below the dependency for CapacitorCordova:

s.dependency 'CapacitorCordova'
s.dependency 'Kommunicate'

iOS

If you are using other plugin which use pods, then check the Podfile generated under platforms/ios directory. After installing the Kommunicate plugin, the existing pods in the Podfile might get replaced by the Kommunicate pod. To make it work with Kommunicate, follow the below steps:

1. Copy the existing Pod dependencies before adding Kommunicate plugin
2. Add Kommunicate plugin. The Podfile will now have Kommunicate dependency.
3. Add the copied Pod depedencies from step 1 below the Kommunicate dependency in the Podfile.

Get your App Id

Sign up for Kommunicate to get your APP_ID. This APP_ID is used to create/launch conversations.

Declare kommunicate variable

Cordova

If you are using native Cordova without Ionic, you can simply call functions by using kommunicate. However if any problem occurs, declare a kommunicate variable:

In typescript(.ts file) declare the variable as below:

 declare var kommunicate: any;

In javascript(.js file) declare the variable as below:

 var kommunicate;

Ionic

If you are using the Ionic framework with cordova or capacitor:

1. In your app/app-module.ts file add the below import:

  import { Kommunicate } from '@ionic-native/kommunicate/ngx';

Then add Kommunicate entry inside providers in the same file.

2. Import Kommunicate in the file you want to use the Kommunicate functions in as below:

import { Kommunicate } from '@ionic-native/kommunicate/ngx';

Then, create a member variable of the imported type in the constructor of the same class as below:

constructor(private kommunicate: Kommunicate) { }

Now use the kommunicate variable to access the functions.

Launch chat

Kommunicate provides conversationBuilder function to create and launch chat directly saving you the extra steps of authentication, creation, initialization and launch. You can customize the process by building the conversationObject according to your requirements. To launch the chat you need to create a conversation object. This object is passed to the conversationBuilder function and based on the parameters of the object the chat is created/launched.

NOTE: Installation section does everything internally that is documented in all other sections(authentication section, conversation section).

If you want to create and launch the conversation then refer to conversation section.

The conversation section can be followed if you want to explore the docs more instead of just using the installation section.

Below are some examples to launch chat in different scenarios:

Launch chat for visitor

If you would like to launch the chat directly without the visiting user entering any details, then use the methods given below:

First create a conversation object:

let conversationObject = {
     'appId' : '<APP_ID>' // The [APP_ID](https://dashboard.kommunicate.io/settings/install) obtained from kommunicate dashboard.
}

Cordova

If you are using native Cordova:

 kommunicate.conversationBuilder(conversationObject, (clientChannelKey) => {
     //The response will be a clientChannelKey which is used for launching a particular conversation.
     console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey);
  }, (error) =>{
      console.log("Kommunicate create conversation failed : " + error);
  });

Ionic

If you are using the ionic framework:

this.kommunicate.conversationBuilder(conversationObject)
    .then((clientChannelKey: any) => console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey))
    .catch((error: any) => console.error("Error creating conversation." + error));
    

NOTE: This installation code works on Android and iOS and it may not work on Web.

Launch chat for visitor with lead collection

If you need the user to fill in details like phone number, emailId and name before starting the support chat then launch the chat with withPreChat flag as true. In this case you wouldn't need to pass the kmUser. A screen would open up for the user asking for details like emailId, phone number and name. Once the user fills the valid details (atleast emailId or phone number is required), the chat would be launched.

First creat a conversation object as you previously:

let conversationObject = {
     'appId' : '<APP_ID>', // The [APP_ID](https://dashboard.kommunicate.io/settings/install) obtained from kommunicate dashboard.
     'withPreChat' : true
}

Sample code:

This code can be added in onclick of any button or on opening the page.

import { Component } from '@angular/core';
import { NavController } from 'ionic-angular';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})
export class HomePage {

  constructor(public navCtrl: NavController) {

     kommunicate.conversationBuilder({
     'appId' : 'APP_ID', //Your APP ID
     'withPreChat' : true //PRE CHAT form
}, (clientChannelKey) => {
     //The response will be a clientChannelKey which is used for launching a particular conversation.
     console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey);
  }, (error) =>{
      console.log("Kommunicate create conversation failed : " + error);
  });


}

}

declare var kommunicate: any;

Cordova

If you are using native Cordova:

 kommunicate.conversationBuilder(conversationObject, (clientChannelKey) => {
     console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey);
  }, (error) =>{
      console.log("Kommunicate create conversation failed : " + error);
  });

Ionic

If you are using the ionic framework:

this.kommunicate.conversationBuilder(converationObject)
    .then((clientChannelKey: any) => console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey))
    .catch((error: any) => console.error("Error creating conversation." + error));

Launch chat with existing user

If you already have the user details then create a KMUser object using the details and launch the chat. Use the method as below to create KMUser with already existing details:

First create a user and a conversation object:

let user = {
      'userId' : '<USER_ID>',   //Replace it with the userId of the logged in user
      'password' : '<PASSWORD>'  //Put password here if user has password, ignore otherwise
}

let conversationObject = {
     'appId' : '<APP_ID>', // The [APP_ID](https://dashboard.kommunicate.io/settings/install) obtained from kommunicate dashboard.
     'kmUser' : JSON.stringify(user)
}

Cordova

If you are using native Cordova:

 kommunicate.conversationBuilder(conversationObject, (clientChannelKey) => {
     console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey);
  }, (error) =>{
      console.log("Kommunicate create conversation failed : " + error);
  });

Ionic

If you are using the ionic framework:

this.kommunicate.conversationBuilder(converationObject)
    .then((clientChannelKey: any) => console.log("Kommunicate create conversation successful the clientChannelKey is : " + clientChannelKey))
    .catch((error: any) => console.error("Error creating conversation." + error));

If you have a different use-case and would like to customize the chat creation, user creation and chat launch, you can use more parameters in the conversationObject.

Below are all the parameters you can use to customize the conversation according to your requirements:

Parameter	Type	Description
appId	String	The APP_ID obtained from kommunicate dashboard
kmUser	KMUser	Optional, Pass the details if you have the user details, ignore otherwise. The details you pass here are used only the first time, to login the user. These login details persists until the app is uninstalled or you call logout.
withPreChat	boolean	Optional, Pass true if you would like the user to fill the details before starting the chat. If you have user details then you can pass false or ignore.
isSingleConversation	boolean	Optional, Pass true if you would like to create only one conversation for every user. The next time user starts the chat the same conversation would open, false if you would like to create a new conversation everytime the user starts the chat. True is recommended for single chat
metadata	Any	Optional. This metadata if set will be sent with all the messages sent from that device. Also this metadata will be set to the conversations created from that device.
agentIds	Array of String	Optional, Pass the list of agents you want to add in this conversation. The agent ID is the email ID with which your agent is registered on Kommunicate. You may use this to add agents to the conversation while creating the conversation. Note that, conversation assignment will be done on the basis of the routing rules set in the Conversation Rules section. Adding agent ID here will only add the agents to the conversation and will not alter the routing rules.
botIds	Array of String	Optional, Pass the list of bots you want to add in this conversation. Go to bots -> Manage Bots -> Copy botID . Ignore if you haven't integrated any bots. You may use this to add any number of bots to the conversation while creating the conversation. Note that this has no effect on the conversation assignee, as the Conversation Rules set forth in the Dashboard will prevail.
conversationAssignee	String	Optional, Pass either the agentId or botId. The conversation created will skip the routing rules and will be assigned to this agent or bot. You also need to pass the agentId in agentIds array or botId in the botIds array, if you are using the conversationAssignee parameter
teamId	String	Optional, Pass this teamId so that the conversation created will skip the routing rules and will be assigned to this team.
clientConversationId	String	Optional, Pass the unique id using which you can recognize the conversation. For e.g If you have a shopping app and each order has its specific conversation, the orderId of the order can be used as a clientConversationId. In this case everyId will have its specific conversation.
conversationTitle	String	Optional, Pass the custom title for a conversation. Use this if you would like to display a custom title instead of the conversation assignee name.
createOnly	boolean	Optional, Pass true if you need to create the conversation and not launch it. In this case you will receive the clientChannelKey of the created conversation in the success callback function.