SmartlyQ Chat SDK Adapter

Build a multi-platform chatbot on the SmartlyQ unified inbox. SmartlyQ aggregates DMs and comments from every connected social account and fires signed webhooks; this adapter verifies them, normalizes them, and hands them to your handler code with reply-capable helpers.

Write once - works on every platform your accounts cover (Instagram, Facebook, X, TikTok, LinkedIn, and the rest).

Platforms -> SmartlyQ unified inbox -> webhook -> this adapter -> your bot
                                                       |
                                 replies sent back via the SmartlyQ API

Installation

npm install @smartlyqofficial/chat-sdk-adapter

Three steps to a multi-platform chatbot

1. Get your SmartlyQ API key - from the Developer Dashboard; set it as SMARTLYQ_API_KEY.

2. Create a webhook subscribed to message.received and comment.received, pointing at your app. Save the whsec_... signing secret it returns.

3. Add the adapter to your app:

// app/api/smartlyq/route.ts (Next.js App Router)
import { createAdapter, toFetchHandler } from '@smartlyqofficial/chat-sdk-adapter';

const adapter = createAdapter({
  webhookSecret: process.env.SMARTLYQ_WEBHOOK_SECRET!,
  // apiKey: taken from SMARTLYQ_API_KEY automatically
})
  .onMessage(async ({ message, thread }) => {
    // Every DM from every platform lands here, normalized.
    if (message.text.toLowerCase().includes('pricing')) {
      await thread.post('Our plans start at... - full details: https://example.com/pricing');
    }
  })
  .onComment(async ({ comment, reply }) => {
    if (!comment.isReply) {
      await reply(`Thanks ${comment.authorName ?? 'friend'}!`);
    }
  });

export const POST = toFetchHandler(adapter);

Express instead? Mount with a raw body and toNodeHandler:

import express from 'express';
import { toNodeHandler } from '@smartlyqofficial/chat-sdk-adapter';

app.post('/webhooks/smartlyq', express.raw({ type: '*/*' }), toNodeHandler(adapter));

Wiring an AI reply

The handler is plain code - call any model you like:

adapter.onMessage(async ({ message, thread }) => {
  const history = await thread.fetchMessages();
  const answer = await yourModel.respond(message.text, history);
  await thread.post(answer);
});

Prefer zero code? SmartlyQ also has a built-in chatbot builder with an inbox bridge - train it on your content in the dashboard and skip the adapter entirely. This package is for when you want full control.

Security

• Every delivery is verified against your whsec_... secret (HMAC-SHA256, X-SmartlyQ-Signature: t=...,v1=..., 5-minute replay window) before your handlers run. Unverified requests get a 401.
• Pass the raw request body to the adapter - JSON-parsing middlewares break signature verification.
• Events other than message.received / comment.received are acknowledged and ignored, so a chat endpoint never causes webhook retries.

API

| Export | Purpose | | --- | --- | | createAdapter(options) | Build an adapter (webhookSecret required; apiKey or a preconfigured client optional) | | .onMessage(handler) | Handle incoming DMs - ctx: { message, thread: { id, post, fetchMessages }, raw } | | .onComment(handler) | Handle incoming comments - ctx: { comment, reply, raw } | | adapter.handleWebhook(rawBody, signatureHeader) | Framework-agnostic core - returns { status, body } | | toFetchHandler(adapter) | Request/Response wrapper (Next.js, Remix, Bun, Deno) | | toNodeHandler(adapter) | Node http / Express wrapper (raw body required) | | verifySignature(rawBody, header, secret) | Standalone signature check |

License

MIT