Chatbot Widget

Live Data From Your API

Show live prices, stock, order status and free slots in your chatbot. Connect a Shopify or WooCommerce store with its keys, or build one endpoint that answers in our JSON format; the chatbot shows the answer as cards.

In short

A visitor asks "red shoes under 2000?". Our server recognises the question, reads your store or calls your endpoint with ?action=product_search&q=red+shoes&price_max=2000, checks the answer and shows product cards in the chat. Your keys and URL never reach the visitor's browser. It only reads: nothing is booked or changed. Each answer uses 1 credit, on the Starter plan and above.

Shopify and WooCommerce: no code

Open Dashboard > your chatbot > Live data and choose your store. A connected store answers product search, product details, categories and order status. For a private lookup the chatbot checks the visitor's phone or email against the order itself, and shows only the status, total and payment state: never a name or address.

WooCommerce: in WordPress go to WooCommerce > Settings > Advanced > REST API, add a key with Read permission, and paste the consumer key and secret. Your site must use https. Order lookups use the WooCommerce order ID; a plugin that changes order numbers is not supported yet.
Shopify: in the Shopify Dev Dashboard, under the organization your store belongs to, create an app with only read_products and read_orders, allow it customer data access so it can check the phone or email, release it and install it on your store. Paste its Client ID and secret. An older custom app's access token also works. By default Shopify lets an app read only the last 60 days of orders.

Anything else, including delivery to a pincode and your own actions, needs your own endpoint, described below.

Your own endpoint: set it up

Open Dashboard > your chatbot > Live data, paste your endpoint's https URL and choose your business type. Saving creates your secret, shown once.
Build the endpoint from the starter code below and press Verify endpoint.
Open each action, read the format it expects, and press Run test to see the card a visitor would see, with every problem named by its field.
Switch on the actions you built. For private ones, first set allowed domains.

What we send you

One URL handles everything: the action name is in ?action=. Public actions are a GET with the params in the URL. Private actions are a POST with the params in the JSON body, because a phone number in a URL ends up in access logs.

requests.http HTTP

GET /rsflowhub?action=product_search&q=red+shoes&price_max=2000&limit=5 HTTP/1.1
Host: shop.example.com
Accept: application/json
User-Agent: RSFlowHub-LiveData/1
X-RSFlowHub-Contract: 1.0
X-RSFlowHub-Action: product_search
X-RSFlowHub-Request-Id: ld_8f2c61d0a7b14e09
X-RSFlowHub-Timestamp: 1793923200
X-RSFlowHub-Signature: sha256=<hex hmac>

POST /rsflowhub?action=order_status HTTP/1.1
Content-Type: application/json
(the same headers)

{"params":{"order_id":"ORD-10482","phone":"+919876543210"}}

Check the signature on every call. It is sha256= + HMAC-SHA256 of {timestamp}.{METHOD}.{path and query}.{sha256 of the body} with your secret. Refuse a timestamp older than 5 minutes. The visitor's IP, cookies and browser details are never forwarded. If your API needs its own token too, add it under Extra login.

Starter code

This checks the signature and answers the verify call. Add one block per action. Treat every param as untrusted text and use prepared statements.

rsflowhub.php

<?php
// rsflowhub.php: put this on your site and paste its https URL into RSFlowHub.
$secret = getenv('RSFLOWHUB_SECRET'); // the lds_... secret from your dashboard

$body = file_get_contents('php://input');
$time = $_SERVER['HTTP_X_RSFLOWHUB_TIMESTAMP'] ?? '';
$sent = $_SERVER['HTTP_X_RSFLOWHUB_SIGNATURE'] ?? '';
$signed = $time . '.' . $_SERVER['REQUEST_METHOD'] . '.' . $_SERVER['REQUEST_URI'] . '.' . hash('sha256', $body);
$expected = 'sha256=' . hash_hmac('sha256', $signed, $secret);

header('Content-Type: application/json');

// Refuse anything not signed by RSFlowHub in the last 5 minutes.
if (abs(time() - (int) $time) > 300 || ! hash_equals($expected, $sent)) {
    http_response_code(401);
    exit(json_encode(['rsflowhub' => '1.0', 'status' => 'error']));
}

$action = $_GET['action'] ?? '';
// Public actions send params in the URL, private ones in the JSON body.
$params = $_SERVER['REQUEST_METHOD'] === 'POST' ? (json_decode($body, true)['params'] ?? []) : $_GET;

// The verify button: prove you hold the secret.
if ($action === 'ping') {
    exit(json_encode([
        'rsflowhub' => '1.0',
        'status' => 'ok',
        'type' => 'ping',
        'data' => ['challenge_response' => hash_hmac('sha256', $params['challenge'] ?? '', $secret)],
    ]));
}

// Add one block per action: read your database and answer in the format shown under that action.
// Use prepared statements: treat every param as untrusted text.
exit(json_encode(['rsflowhub' => '1.0', 'status' => 'error', 'message' => 'Not set up yet']));

// Express. Paste this route's https URL into RSFlowHub.
const crypto = require('crypto');
const express = require('express');
const app = express();
const secret = process.env.RSFLOWHUB_SECRET; // the lds_... secret from your dashboard

const hmac = (text) => crypto.createHmac('sha256', secret).update(text).digest('hex');

// Raw body: the signature covers the exact bytes we sent.
app.all('/rsflowhub', express.raw({ type: '*/*' }), (req, res) => {
  const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
  const time = req.get('X-RSFlowHub-Timestamp') || '';
  const sent = Buffer.from(req.get('X-RSFlowHub-Signature') || '');
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
  const expected = Buffer.from('sha256=' + hmac(`${time}.${req.method}.${req.originalUrl}.${bodyHash}`));

  // Refuse anything not signed by RSFlowHub in the last 5 minutes.
  const fresh = Math.abs(Date.now() / 1000 - Number(time)) <= 300;
  if (!fresh || sent.length !== expected.length || !crypto.timingSafeEqual(sent, expected)) {
    return res.status(401).json({ rsflowhub: '1.0', status: 'error' });
  }

  const action = req.query.action;
  // Public actions send params in the URL, private ones in the JSON body.
  const params = req.method === 'POST' ? JSON.parse(body.toString() || '{}').params || {} : req.query;

  // The verify button: prove you hold the secret.
  if (action === 'ping') {
    return res.json({
      rsflowhub: '1.0',
      status: 'ok',
      type: 'ping',
      data: { challenge_response: hmac(String(params.challenge || '')) },
    });
  }

  // Add one block per action: read your database and answer in the format shown under that action.
  // Use prepared statements: treat every param as untrusted text.
  res.json({ rsflowhub: '1.0', status: 'error', message: 'Not set up yet' });
});

app.listen(3000);

What you answer

Always HTTP 200 (404 and 422 are also read if the body is in this format). Only rsflowhub and status are always required. Fields we do not know are ignored and never reach a visitor.

response.json JSON

{
    "rsflowhub": "1.0",
    "status": "ok",
    "type": "items",
    "message": "A short line above the cards",
    "data": {
        "items": [
            {
                "title": "Only the title is required"
            }
        ]
    },
    "meta": {
        "total": 14,
        "next_cursor": "p2",
        "cache_seconds": 120
    },
    "suggestions": [
        "Quick reply chips"
    ],
    "buttons": [
        {
            "label": "View all",
            "url": "https://shop.example.com/shoes"
        }
    ]
}

meta.next_cursor adds a Show more button; we send it back as cursor.
meta.cache_seconds lets us reuse a public answer, up to 60 minutes. Private answers are never cached.

Every status, and what the visitor sees

status	When	Visitor sees
`ok`	Found it. Needs `type` and `data`.	The cards
`empty`	The search worked and nothing matched.	Your `message`, or "I could not find anything for that"
`not_found`	Unknown id, or the order and phone do not match. Answer the same for both.	The same fixed words for both, so nobody can guess orders
`invalid_input`	A bad param, with `fields`: `{"pincode":"Enter a 6-digit pincode"}`.	Asks for that field again, in your words
`closed`	Closed now, no delivery there, sold out, admissions shut.	Your `message`
`needs_human`	A person should take over.	Your `message`, then the Talk to Human flow
`error`	Something failed on your side.	The normal chatbot, or your "contact us" text for a private lookup

A 401, 403, 429, 5xx, a redirect, a slow answer (over 4 seconds), a body over 256 KB or broken JSON counts as a failure. It is logged for you and never shown to the visitor.

The 5 card types

Every action answers with one of these (or type: "text" with data.text). Each industry's sample below shows them with real fields.

type	What it is	Used for
`items`	A list of cards	Products, dishes, courses, doctors, flats, packages, cars, plans, offers, branches.
`detail`	One thing in full	One product, property, package or vehicle.
`status`	Where something stands	Order, return, appointment, booking, application, filing, service job.
`slots`	What is free and when	Tables, appointments, site visits, demo classes, test drives, departures.
`facts`	A yes/no or a small table	Delivery check, gold rates, fee breakup, EMI, on-road price, open now.

Limits: 10 items, 12 slots, 8 attributes and 4 buttons per card, title 120 characters, description 400. Over a limit is cut, not an error, and the tester warns you. Links must be https (buttons may also use mailto: and tel:), images https. HTML is removed from all text.

Actions for your industry

You build only the ones you switch on. Private ones are POSTed and ask the visitor for a reference and phone, which your API must check together. Every industry can also use branches.

action	What it does	Access	Params	Answers with
`product_search`	Find products by words, category, price or stock.	Public	`q`, `category`, `price_min`, `price_max`, `in_stock`, `sort`, `limit`, `cursor`	`items`
`product_detail`	One product in full: stock, variants, specifications.	Public	`id`*	`detail`
`categories`	The categories a shopper can browse.	Public	`parent`	`items`
`offers`	Current offers, with a code the shopper can copy.	Public	`q`	`items`
`delivery_check`	Whether you deliver to a pincode, how fast, and if cash on delivery works.	Public	`pincode`*, `id`	`facts`
`order_status`	Where an order is. The shopper gives the order number and their phone or email.	Private	`order_id`*, `phone`, `email`	`status`
`return_status`	Where a return or refund stands.	Private	`order_id`*, `phone`, `email`	`status`
`branches`	Your outlets with address, hours and a map link.	Public	`q`	`items`

product_search.json JSON

{
    "rsflowhub": "1.0",
    "status": "ok",
    "type": "items",
    "message": "Found 2 products under ₹2,000",
    "data": {
        "items": [
            {
                "id": "SKU-221",
                "title": "Red Running Shoes",
                "subtitle": "Stride",
                "description": "Lightweight mesh, sizes 6-11.",
                "image": "https://cdn.example.com/p/221.jpg",
                "url": "https://shop.example.com/p/221",
                "price": {
                    "amount": 1899,
                    "currency": "INR",
                    "compare_at": 2499
                },
                "availability": {
                    "state": "in_stock",
                    "label": "In stock"
                },
                "rating": {
                    "value": 4.4,
                    "count": 182
                },
                "badge": "24% off",
                "attributes": [
                    {
                        "label": "Size",
                        "value": "6-11"
                    }
                ],
                "buttons": [
                    {
                        "label": "Buy now",
                        "url": "https://shop.example.com/cart/add/221"
                    }
                ]
            },
            {
                "id": "SKU-305",
                "title": "Crimson Walking Shoes",
                "price": {
                    "amount": 1499,
                    "currency": "INR"
                },
                "availability": {
                    "state": "low_stock",
                    "label": "Only 3 left"
                },
                "url": "https://shop.example.com/p/305"
            }
        ]
    },
    "meta": {
        "total": 14,
        "next_cursor": "p2",
        "cache_seconds": 120
    },
    "suggestions": [
        "Delivery to my pincode",
        "Track my order"
    ],
    "buttons": [
        {
            "label": "View all",
            "url": "https://shop.example.com/shoes"
        }
    ]
}