Integrations / Starter chatbot

Starter chatbot logo

Chatbots · Webhook + send API

Starter chatbot + Sendjade

A minimal Node bot that receives messages and replies, to build your own on.

Live API · real-phone check pending

What you can automate

  • Answer opening-hours questions automatically
  • Collect an order then hand over to a person
  • Route keywords to different flows

Before you start

  • A Sendjade account with a connected instance (status Authorized). See Getting started.
  • Your **idInstance** (shown on the instance page in the console) and **apiTokenInstance** (shown once when you created the instance; press Generate new token if you lost it). Use a spare number while testing.
  • Node 20+ and a public HTTPS URL for the webhook (a tunnel works while testing).

Set it up

  1. Enable incoming messages

    Register your endpoint under Webhooks (Admin role) or with POST /api/v1/webhooks. Choose the native format (default) and the events you need, such as message.received, message.delivered or message.failed. The signing secret is shown once. Point it at your server's /webhook URL.

  2. Run the bot

    Verify the signature, ignore groups and duplicates, then reply with simple rules.

    bot.mjs
    import crypto from 'node:crypto';
    
    // Returns true only for a genuine, recent Sendjade delivery. `raw` is the exact request body string.
    function verifySendjade(raw, header, secret) {
      const parts = Object.fromEntries((header || '').split(',').map((p) => p.trim().split('=')));
      const t = Number(parts.t);
      if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > 300) return false;       // stale: possible replay
      const expected = crypto.createHmac('sha256', secret).update(t + '.' + raw).digest('hex');
      return parts.v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
    }
    
    import express from 'express';
    const app = express();
    const seen = new Set();            // use Redis or a database in production
    
    app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
      const raw = req.body.toString('utf8');
      if (!verifySendjade(raw, req.get('X-Sendjade-Signature'), process.env.SENDJADE_WEBHOOK_SECRET)) return res.sendStatus(401);
      res.sendStatus(200);             // answer fast, work after
    
      const delivery = req.get('X-Sendjade-Delivery');
      if (seen.has(delivery)) return;  // retries re-send the same delivery id
      seen.add(delivery);
    
      const { event, data } = JSON.parse(raw);
      if (event !== 'message.received' || data.chatId.endsWith('@g.us')) return; // only direct chats
      const reply = /hours/i.test(data.text || '') ? 'We are open 9am to 6pm, Monday to Saturday.' : 'Thanks! A team member will reply shortly.';
    
      await fetch('https://api.sendjade.com/waInstance' + process.env.SENDJADE_ID_INSTANCE + '/sendMessage/' + process.env.SENDJADE_TOKEN_INSTANCE, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ chatId: data.chatId, message: reply }),
      });
    });
    app.listen(8080);
  3. Be a good citizen

    Only answer people who messaged you, keep replies relevant, and always let people stop messages (Sendjade adds anyone who replies STOP to the opt-out list automatically). Automated replies at scale put a number at risk.

Test it

Message your connected number from another phone with the word "hours".

Troubleshooting

The bot replies twice

Webhooks are retried when your endpoint does not answer 2xx quickly. Ignore deliveries whose X-Sendjade-Delivery id you have already handled, as the example does.

The signature check always fails

Verify against the exact raw body (use express.raw, not express.json) and the secret of this webhook. A rotated secret invalidates the old one.

I get 401 unauthorized

The idInstance or token in the URL is wrong. Copy both again from the console. Generating a new token makes the old one stop working immediately.

I get 409 instance_not_connected

The instance is not Authorized yet. Open it in the console, press Connect and scan the QR code.

I get 400 invalid_chat_id

Use international format with digits only, e.g. 2348012345678 (or 2348012345678@c.us). Remove spaces, dashes and the leading zero of the local number.

I get 422 recipient_opted_out

That person replied STOP (or was added to the opt-out list). Sendjade refuses to message them. Remove the number from Opt-outs only if they asked to hear from you again.

I get 429 daily_limit_reached or rate_limited

The number reached its 24-hour sending cap (default 500) or you are calling too fast. The cap protects your number from restriction. Slow down, and raise the cap only if your volume is genuine.

Ask AI to help me integrate Starter chatbot

Copy this prompt into ChatGPT, Claude or any assistant. It already knows Sendjade’s API, so the answer matches our endpoints.

The prompt is plain text that you copy yourself. Never paste real keys into an assistant; use placeholders.