Quickstart

This guide gets you from zero to a synced contact in your Whatbot inbox.

1. Get your API key

Every tenant (workspace) has its own API key. It scopes every request to that one workspace, so a key for Acme can only read and write Acme’s data.

Ask your Whatbot admin for a key, or generate one in Settings → API keys. It looks like this:

wa_live_5b14e3379b56d72420dfc86659b74b0b5752c8a7201c63b3

Caution

Treat the key like a password. It is stored hashed — it can’t be shown again after creation, so save it somewhere safe. Lost it? Revoke and mint a new one.

2. Send it as a header

Every request carries the key in the X-API-Key header:

X-API-Key: wa_live_xxxxxxxxxxxxxxxx

3. Push your first contact

Contacts are the people you’ll message. Upsert one (or thousands) with a single call. The body is a JSON array.

cURL

curl -X POST https://api.whatbot.in/public/v1/contacts \
  -H "X-API-Key: wa_live_xxx" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "phone": "9876543210",
      "name": "Ravi Kumar",
      "tags": ["gold", "vip"],
      "opt_in": true,
      "attributes": { "city": "Chennai", "budget": "15L" }
    }
  ]'

Node.js

const res = await fetch("https://api.whatbot.in/public/v1/contacts", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.WHATBOT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    {
      phone: "9876543210",
      name: "Ravi Kumar",
      tags: ["gold", "vip"],
      opt_in: true,
      attributes: { city: "Chennai", budget: "15L" },
    },
  ]),
});
console.log(await res.json()); // { upserted: 1, received: 1 }

Python

import requests

requests.post(
    "https://api.whatbot.in/public/v1/contacts",
    headers={"X-API-Key": "wa_live_xxx"},
    json=[
        {
            "phone": "9876543210",
            "name": "Ravi Kumar",
            "tags": ["gold", "vip"],
            "opt_in": True,
            "attributes": {"city": "Chennai", "budget": "15L"},
        }
    ],
    timeout=20,
)

You’ll get back:

{ "upserted": 1, "received": 1 }

Done

The contact now appears in your Whatbot inbox. Re-sending the same phone updates it — contacts are upserted by phone number.

4. Next steps

Contacts API reference Every field, custom attributes, and upsert behavior.

Bulk import (CSV) Upload a spreadsheet instead of writing code.

Send a message Start a conversation with a template.

Automate with n8n Wire it to your CRM so contacts sync automatically.