Custom Channel

The Custom Channel allows you to connect any third-party messaging platform to klink.cloud using webhooks.

Once connected, messages from your system will appear in the klink.cloud Unified Inbox, and agent replies can be sent back to your platform automatically. Text and media messages (images, videos, audio, and files) are supported in both directions.

---

Where to Find Custom Channel

1. Go to Settings

2. Click Message Integration

3. Select Custom Channel

4. Click Create / Setup Custom Channel

---

How Custom Channel Works

Custom Channel uses two webhooks:

• Outbound Webhook klink.cloud → sends agent replies to your server

• Inbound Webhook Your server → sends customer messages into klink.cloud

Both are required for two-way messaging.

---

Step 1: Set Up Outbound Webhook

(klink.cloud → Your System)

This step allows klink.cloud to deliver agent replies to your server.

Steps

1. In Outbound Webhook, enter your server URL:

   https://your-webhook-server.com/webhook

2. (Optional) Add headers if your server requires authentication:

   Authorization: Bearer YOUR_API_KEY

3. Click Next

What This Does

Whenever an agent (or bot) replies in klink.cloud, the reply — text or media — is sent to your server in real time as an HTTPS POST request.

---

Step 2: Set Up Inbound Webhook

(Your System → klink.cloud)

This step allows your system to send messages into klink.cloud.

Steps

1. Copy the Inbound Webhook URL shown on screen Example:

   https://me.klink.cloud/custom-channel/xxx/xxx/webhook

2. Use this URL in your backend or application to send messages to klink.cloud

3. Click Complete Setup

🔒 Keep this URL private. Anyone with this URL can send messages to your inbox.

---

Sending Messages to klink.cloud (Inbound Webhook)

Endpoint

POST {Inbound Webhook URL}

Headers

Content-Type: application/json

Text Message

{
  "messageId": "msg-001",
  "content": "Hello from our custom platform",
  "sender": {
    "id": "user-123",
    "name": "John Doe",
    "email": ""
  },
  "timestamp": 1765440758023,
  "type": "text",
  "conversationId": "ca7de328-32da-4468-bae0-872e94f56be0"
}

Field Reference

Field	Required	Description
type	✅	text, image, video, audio, or file
conversationId	✅	Your conversation identifier. Reuse the same value to continue a conversation; a new value starts a new one
sender.id	✅	Unique ID of the customer in your system
sender.name	✅	Display name of the customer
sender.email	Optional	Customer email
content	✅ for text	Message text. For media types it is an optional caption
timestamp	✅	Message time in milliseconds since epoch
messageId	Optional	Your unique message ID. If omitted, klink.cloud generates one
attachment	✅ for media	See Sending Media Messages below

---

Sending Media Messages (Images, Videos, Audio, Files)

Media messages are sent inline as a Base64-encoded attachment.

{
  "messageId": "msg-003",
  "content": "Optional image caption",
  "sender": {
    "id": "user-123",
    "name": "John Doe",
    "email": ""
  },
  "timestamp": 1765440900000,
  "type": "image",
  "conversationId": "ca7de328-32da-4468-bae0-872e94f56be0",
  "attachment": {
    "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "fileName": "photo.png",
    "mimeType": "image/png",
    "fileSize": 68
  }
}

Attachment Fields

Field	Required	Description
data	✅	File content as Base64 — either a raw Base64 string or a data:<mime>;base64, URL
fileName	✅	File name including extension (e.g. invoice.pdf)
mimeType	✅	MIME type (e.g. image/png, video/mp4, audio/mpeg, application/pdf)
fileSize	✅	Size of the decoded file in bytes — must exactly match the decoded Base64 data

Important: The maximum attachment size is 2.5 MB (2,621,440 bytes) after Base64 decoding. Requests with a larger attachment, or where fileSize does not match the decoded size, are rejected with a 400 error.

---

Receiving Messages from klink.cloud (Outbound Webhook)

klink.cloud sends a POST request to your Outbound Webhook URL whenever an agent or bot replies. Your configured request headers are included on every call. Respond with a 2xx status code to acknowledge delivery.

Text Reply

{
  "type": "text",
  "conversationId": "ca7de328-32da-4468-bae0-872e94f56be0",
  "channelId": "0196c8a1-1111-2222-3333-444455556666",
  "userId": "user-123",
  "content": "How can I help you?",
  "messageId": "8f14e45f-ceea-4a7a-9f3a-1c1d2e3f4a5b",
  "sender": {
    "id": "agent-001",
    "name": "Support Agent"
  }
}

Media Reply

For image, video, audio, and file replies, the payload includes an attachment with a download URL instead of Base64 data:

{
  "type": "image",
  "conversationId": "ca7de328-32da-4468-bae0-872e94f56be0",
  "channelId": "0196c8a1-1111-2222-3333-444455556666",
  "userId": "user-123",
  "content": "",
  "messageId": "9a25f56a-dffb-4b8b-8e4b-2d2e3f4a5b6c",
  "sender": {
    "id": "agent-001",
    "name": "Support Agent"
  },
  "attachment": {
    "url": "https://media.klink.cloud/…signed-url…",
    "fileName": "photo.png",
    "fileSize": 245120,
    "mimeType": "image/png"
  }
}

Note: Attachment URLs are time-limited signed links. Download the file promptly (or forward the URL immediately) rather than storing the link long-term.

---

Testing the Integration

• Use the Sample Inbound Payloads provided in the UI (both text and image examples are included)

• Send them via Postman, cURL, or your backend

• Confirm the message appears in the inbox

---

Security Best Practices

• Always use HTTPS

• Use headers for authentication

• Do not expose inbound webhook URL publicly

• Validate all incoming requests

---

Supported Message Types

Type	Inbound (to klink.cloud)	Outbound (from klink.cloud)
Text	✅ Supported	✅ Supported
Image	✅ Supported (Base64, ≤2.5 MB)	✅ Supported (signed URL)
Video	✅ Supported (Base64, ≤2.5 MB)	✅ Supported (signed URL)
Audio	✅ Supported (Base64, ≤2.5 MB)	✅ Supported (signed URL)
File / Document	✅ Supported (Base64, ≤2.5 MB)	✅ Supported (signed URL)

---

Typical Use Cases

• Custom chat applications

• Internal company messengers

• AI bots & agents

• CRM or ERP messaging

• Legacy system integrations

---

Need Help?

• 📘 Documentation: https://docs.klink.cloud

• 💬 Support: [e-mail]