Custom AI Agent Integration · Developer Docs

Overview

Custom AI agent integration allows you to integrate with any other AI agent platforms. In this section, learn how to:

Integrating with custom AI agent platform

If you have any AI agent running on platforms other than Dialogflow, you can integrate it with kommunicate by following below steps:

Go to Kommunicate AI agent integration and click on Other AI agent platforms.
Kommunicate will ask you a webhook URL and request header for the webhook. Webhook URL is required at your backend server so that messages sent to AI agent can be forwarded to your server. You can use same webhook for multiple AI agents or can configure different webhook. Kommunicate will send the data to your webhook in below format:

{
    "botId": "AI agent id who has received the message. This id is same as shown in dashboard.",
    "key": "unique id for every message",
    "from": "user id who has sent the message",
    "message": "message sent by user to the AI agent",
    "groupId": "conversation id",
    "metadata": "extra information with message",
    "contentType": "content type of the message (text, html, location, etc)",
    "applicationKey": "your APP_ID shown in Dashboard Install section",
        "source": "identifies if message is sent from web or mobile",
    "eventName": "events ie. WELCOME , KOMMUNICATE_MEDIA_EVENT etc",
    "createdAt": "message sent time"
}

Kommunicate sends the message to your webhook and waits for the response. The timeout limit for the webhook URL is set to the 60 seconds. Your webhook should return the array of message in response in below format:

[{
    "message": "A message can be simple as a plain text"
}, {
    "message": "A message can be a rich message containing metadata",
    "metadata": {
    "contentType": "300",
        "templateId": "6",
        "payload": [{
            "title": "Suggested Reply button 1",
            "message": "Suggested Reply button 1"
        }, {
            "title": "Suggested Reply button 2",
            "message": "Suggested Reply button 2"
        }]
    }
}]

Each object in message array is rendered as separate message in Kommunicate chat widget.

Welcome message from AI agents

Kommunicate sends some specific events to your webhook in eventName property. When a user creates a new conversation Kommunicate sends eventName: WELCOME to your webhook. You can check for this property in payload and reply with a welcome message.

Skip AI agent welcome message

Skip the 'WELCOME' event from dialogflow by setting

 "skipBotEvent":'["WELCOME_EVENT"]'

Skip AI agent welcome message through Settings

var defaultSettings = {
    "skipBotEvent": '["WELCOME_EVENT"]',
};
Kommunicate.updateSettings(defaultSettings);

Skip AI agent welcome message for a specific conversation

var conversationDetail = {
    "skipBotEvent":'["WELCOME_EVENT"]'
};

Kommunicate.startConversation(conversationDetail, function (response) { });

Send attachments to AI agent

When a user attaches a file or shares location, Kommunicate sends eventName: KOMMUNICATE_MEDIA_EVENT to your AI agent along with the attached file information. You can find the file information in KM_CHAT_CONTEXT object in metadata. Below is the sample of webhook payload with attachment detail:

This is sample JSON for file attachment:

{
    "eventName": "KOMMUNICATE_MEDIA_EVENT",
    "metadata": {
        "KM_CHAT_CONTEXT": {
            "attachments": [{
                "type": "image/png", // media type (in form of type/subtype) . Use the regex 'type/*' to get the generic type
                "payload": {
                    "name": "file name",
                    "url": "file url",
                    "size": "size in bytes"
                }
            }]
        }
    },
    "createdAt": 1552638706610,

}

Attachment object for location message

{
    "attachments": [{
        "payload": {
            "lat": "Latitude",
            "lon": "Longitude"
        },
        "type": "location"
    }]
}

Handoff conversation to human agents

You can design your AI agent to handoff the conversation to human agents if the AI agent is not able to answer. You can notify Kommunicate by sending an specific human agent Id or an empty value in "KM_ASSIGN_TO" property in metadata. If empty value is passed Kommunicate will check the conversation rules for human agents configured in dashboard. If human agent id is passed then kommunicate will skip the conversation rules and assign conversation to the mentioned human agent.

below is the sample response of the webhook human agent handoff

[{
  "message": "our human agents will get back to you",
  "metadata": {
    "KM_ASSIGN_TO": ""
  }
}]

Rich Message for custom AI agent

If you want to use Rich Message, pass the Rich Message template as metadata in the message.

Kommunicate renders a valid JSON into Rich Message. Pass the JSON described below as metadata to utilize Rich Messages. This example renders Suggested Replies along with the message:

{
"message":"Do you want more updates?",
"ignoreTextResponse": false,
   "platform":"kommunicate",
   "metadata": {
       "contentType": "300",
       "templateId": "6",
       "payload": [{
           "title": "Yes",
           "message": "Cool! send me more."
       }, {
           "title": "No ",
           "message": "Don't send it to me again"
       }]
   }
}

If you're passing both the text response and custom payload in intent and want to hide the text response you can pass ignoreTextResponse: true.