Live Chat Hub Integration API Documentation

1. Overview

LiveChatHub is a middleware platform that enables integration between Knovvu Virtual Assistant (Magpie) and third‑party live‑agent chat platforms such as Genesys Cloud, Amazon Connect, Twilio, Tegsoft, and others.

The system uses a provider‑based adapter architecture. Each vendor integration is implemented as a separate adapter that conforms to the ILiveChatService interface.

Core Responsibilities

2. Architecture & Conversation Flow

High‑Level Flow

1. Customer requests a live agent via Knovvu VA (Magpie)
2. Magpie calls LiveChatHub to start a conversation
3. LiveChatHub routes the request to the correct provider adapter
4. Adapter creates a session on the live‑agent platform
5. Messages flow bi‑directionally through LiveChatHub
6. Conversation ends either by Magpie or by the agent platform

Sequence Diagram (Conceptual)

• Customer → Magpie → LiveChatHub → Provider Adapter → Agent Platform
• Agent events → Provider Adapter → LiveChatHub → Magpie → Customer

3. Authentication

Token Endpoint

POST /livechathub/connect/token/{provider}

Content‑Type: application/x-www-form-urlencoded

Parameters

Authorization Header

Authorization: Basic base64(username:password)

Response

{
  "access_token": "<jwt>",
  "expires_in": 31536000,
  "token_type": "Bearer",
  "scope": "lc_adapter"
}

4. API Endpoints

All endpoints are available in two forms:

• /livechathub/{endpoint}/{provider}
• /livechathub/generic/{endpoint}/{provider}

4.1 Check Agent Availability

GET /livechathub/agent/availability/{provider}

Query Parameters

Response

{ "totalAgentCapacity": 1 }

4.2 Get Skills / Queues

GET /livechathub/skills/{provider}

Headers

Authorization: Bearer <token>

Query Parameters

Response

["skill1", "skill2", "queue_name"]

4.3 Start Conversation

POST /livechathub/conversation/{provider}

Headers

Authorization: Bearer <token>
Content-Type: application/json

Query Parameters

Request Body

• Microsoft Bot Framework Activity
• Contains customer info, conversation id, channel data, history, and summary

Response

{
  "startConversationSuccess": true,
  "id": "conversation-id",
  "token": "session-token",
  "_status": ""
}

4.4 Send Message

POST /livechathub/send-message/{provider}

Request Body

• Text message
• Optional attachments (files, images, etc.)

Response

{
  "sendMessageSuccess": true,
  "sendMessageError": "",
  "id": "message-id"
}

4.5 Get Conversation Status

GET /livechathub/conversation/status/{provider}

Response

{ "success": true, "error": "" }

4.6 End Conversation

PUT /livechathub/conversation/{provider}

Request Body

{
  "type": "endOfConversation",
  "conversation": { "id": "conversation-id" }
}

5. Webhook (Event Listener)

POST /livechathub/EventListener/{provider}/{option}/

Path Parameters

Optional Query

Supported Events

6. MagpieRequest Model

This object is sent from LiveChatHub to Magpie when agent events occur.

Key Fields

• Text: message content
• Conversation.Id: full conversation identifier
• From: agent info
• Recipient: customer info
• Type: message or event type
• Attachments: optional files
• ChannelData: custom metadata

7. Message Types

8. File Attachments

Supported Categories

9. Magpie Integration Details

9.1 Authentication

• OAuth2 Client Credentials
• Token endpoint: {Magpie.OAuthEndpoint}/connect/token
• Token cached in memory and refreshed automatically

9.2 Sending Messages to Magpie

Endpoint

POST {Magpie.Endpoint}/magpie/api/messages

Required Headers (Derived from Conversation.Id)

9.3 Conversation ID Format (Critical)

The conversation ID must follow this format:

{conversationRootId}_{channelId}_{tenant}_{project[_subproject...]}

Example

260b3b8b-9ee4_TESTCHAT_DEFAULT_TESTHL_SUBPROJECT

Parsed As

10. Conversation End Scenarios

10.1 Magpie → LiveChatHub

• Magpie calls PUT /conversation/{provider}
• Adapter disconnects vendor session

10.2 Provider → Magpie

• Agent ends chat on vendor side
• Provider receives webhook
• Adapter sends endedByAgent event to Magpie

11. Error Handling

12. Notes & Best Practices

• Always validate webhook payloads
• Preserve the same Conversation.Id throughout the flow
• Ensure underscore format correctness
• Send agent disconnect events explicitly
• Attachments should include MIME type and category