Buzzeasy Bot Proxy API

Introduction

Buzzeasy provides an API module for use to integrate custom bot platforms to the Buzzeasy Cloud. This provides functionality to extend on channels available within Buzzeasy to custom bot solutions such as IBM Watson, Google DialogFlow, Amazon Lex etc.

The purpose of this document is to provide the Web Service Interface Contract for the Buzzeasy solution for external bot developers.

Architecture

The Buzzeasy API follows a push model to forward messages and conversations to any integrated platform.

Architecture

Security

Please consult with Buzzeasy team regarding access to the API. The access token can be generated from the Buzzeasy Administration Portal.

Intelligent Connect API

Webhook (HTTPS)

The Buzzeasy platform sends events such as assign conversation and messages to your platform when it occurs on any configured channel. All webhook events are sent to the third party platform by POST requests to your webhook

Events

Assign Conversation

Webhook URL: <ConfiguredURL>
Content Type: JSON

This is the first event that your bot will receive. This event will include the basic information of the conversation.

Attribute	Type	Description
ChatServiceId	String	The Chat Service ID is a platform related identifier. This is only used if configuration is needed from Buzzeasy Configuration API
Addressee	String
CustomerId	String	The Buzzeasy Customer ID. Used to query the Buzzeasy Customer Manager API
CustomerMessage	String	The Customer Message sent from the channel. If workflow is sending to third party immediately, this will always be populated.
CustomerAttachments	List<Attachment>	The Customer Attachments sent from the channel. If workflow is sending to third party immediately, this will always be populated.
ConversationId	String	The Buzzeasy Conversation ID. This conversation ID needs to be persisted throughout the entire conversation for any callback requests e.g. response messages
AdditionalData	Dictionary<string, string>	Any additional data collected from any previous dialog
WorkitemData	Dictionary<string, string>	Any Workitem data collected from any previous dialog
CustomerData	Dictionary<string, string>	Any Customer data collected from any previous dialog

Assign Conversation event example:

{
    "ChatServiceId": 1,
    "Addressee": "Your Bot Name",
    "CustomerId": "52f3bf6d-ca6f-4858-805c-39dd78e1c9c0",
    "CustomerMessage": "hi",
    "CustomerAttachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://api.buzzeasy.com/content/v1.0/dd565583-ec43-440b-98fa-5b44e8bd01be/test.png",
            "content": null,
            "name": "test.png",
            "thumbnailUrl": null
        }
    ],
    "ConversationId": "43875e7035b845a1a7b50091f2cd00df",
    "AdditionalData": {
        "buzzeasy.TenantId": "9cc86f657dbf2f0001da32da"
    },
    "WorkItemData": {},
    "CustomerData": {},
    "Id": "d216ec0d-ae5c-48fe-bb8f-8b7c875e1747",
    "CreationDate": "2020-02-18T19:59:52.6670315Z"
}

Messages

Webhook URL: <ConfiguredURL>/<ConversationId>/messages
Content Type: JSON

This event represents the customer message.

Attribute	Type	Description
ChatServiceId	String	The Chat Service ID is a platform related identifier. This is only used if configuration is needed from Buzzeasy Confiuration API
MessageGuid	String	The unique identifier of the message
CustomerId	String	The Buzzeasy Customer ID. Used to query the Buzzeasy Customer Manager API
MessageBody	String	The Customer Message sent from the channel. If workflow is sending to third party immediately, this will always be populated.
ConversationId	String	The Buzzeasy Conversation ID. This conversation ID needs to be persisted throughout the entire conversation for any callback requests e.g. response messages
Attachments	List<Attachments>	Attachment objects sent over as part of the message
CreatedAt	datetime	Date Time stamp (in UTC) of the creation of the message
SuggestedActions	SuggestedActions	Suggested Action object of any quick replies sent from customer
Summary	String	Not used
AdditionalData	String	Not used
AttachmentLayout	String	Not use

Message event example:

{
    "ChatServiceId": 1,
    "MessageGuid": "0a2066abf540441da52cf7734d083060",
    "CustomerId": "52f3bf6d-ca6f-4858-805c-39dd78e1c9c0",
    "From": "Customer",
    "MessageBody": "This is a message from the customer.",
    "Attachments": [
        {
            "contentType": "image/png",
            "contentUrl": " https://api.buzzeasy.com/content/v1.0/8a7cfbd3-062a-4f87-8b2e-c6cd017cf8de/test.png",
            "content": null,
            "name": "test.png",
            "thumbnailUrl": null
        }
    ],
    "CreatedAt": "2020-02-18T20:00:53.7668159Z",
    "ChannelId": "directline",
    "ConversationId": "43875e7035b845a1a7b50091f2cd00df",
    "SuggestedActions": null,
    "Summary": null,
    "AdditionalData": {},
    "AttachmentLayout": null,
    "Id": "775ee46e-1bbe-45e3-84f5-e02410639c3b",
    "CreationDate": "2020-02-18T20:00:53.7668159Z"
}

Send (HTTPS)

This API is used to send events such as messages and end conversation events. This will then be actioned within the Buzzeasy Platform to send the message to the user within the conversation or end the conversation and clear the task.

Send Message

URL: Geomant to provide URL to send API per environment
Content Type: JSON

Sends a message to the customer.

Attribute	Type	Description	Mandatory
ChatServiceId	String	The Chat Service ID is a platform related identifier. This is only used if configuration is needed from Buzzeasy Confiuration API	yes
Id	String	The unique identifier of the message	yes
CustomerId	String	The Buzzeasy Customer ID. Used to query the Buzzeasy Customer Manager API	no
MessageBody	String	The Customer Message sent from the channel. If workflow is sending to third party immediately, this will always be populated.	no
ConversationId	String	The Buzzeasy Conversation ID. This conversation ID needs to be persisted throughout the entire conversation for any callback requests e.g. response messages	yes
Attachments	List<Attachments>	Attachment objects sent over as part of the message	no
CreatedAt	datetime	Date Time stamp (in UTC) of the creation of the message	no
SuggestedActions	SugestedActions	Suggested Action object of any quick replies sent from customer	no
Summary	String	Not used	no
AdditionalData	Dictionary<String, String>	Not used	no
AttachmentLayout	String	Not used	no

Message example:

{
   "ChatServiceId": 1,
   "MessageGuid": "8c6ee47e-caa5-4d7e-9e68-521b5a402d1f",
   "CustomerId": "1d9c1916-b5bb-423a-985c-a28599fb77b2",
   "From": "Bot",
   "MessageBody": "Message from your bot.",
   "Attachments": null,
   "CreatedAt": "2020-02-18T20:43:03.9874984Z",
   "ChannelId": "facebook",
   "ConversationId": "9cbc54600b464be3bb82be5d762d0249",
   "SuggestedActions": null,
   "Summary": null,
   "AdditionalData": null,
   "AttachmentLayout": null,
   "Id": "4c7d0ebe-9582-4f68-aaff-8a5f518dfc31",
   "CreationDate": "2020-02-18T20:43:03.9856377Z"
}

End Conversation

URL: Buzzeasy to provide URL to send API per environment
Content Type: JSON

Closes the conversation.

Attribute	Type	Description	Mandatory
ContinueWithFlow	Bool	Indicates if the workflow should continue.	no
ConversationId	String	The Buzzeasy Conversation ID. Unique identifier for the conversation. This ID needs to be persisted throughout the conversation.	yes
CustomerId	String	The Buzzeasy Customer ID. Used to query the Buzzeasy Customer Manager API	no
AdditionalData	Dictionary<String, String>	Not used	no
CustomerData	Dictionary<String, String>	You can update the customer by adding a key value pair into this dictionary. The key must be a customer field name e.g: "FirstName" and the value is the new value.	no

End Conversation example:

{
   "Sender": "Bot",
   "ContinueWithFlow": true,
   "ConversationId": "fbcdd956fbcf4a9eb6d4b683b389a0a8",
   "CustomerId": "912dd1cc-a84c-4506-8b81-78ee4b8f8183",
   "AdditionalData": null,
   "CustomerData": {
      "FirstName": "Kevin"
   },
   "Id": "7c7a5cf5-992e-49b4-a010-d26dc43d15be",
   "CreationDate": "2020-02-18T20:43:04.860573Z"
}