Quickstart

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

1. Get your API key

Every API key belongs to one workspace. It scopes every request to that workspace, so a key for Acme can only read and write Acme’s data. A workspace can hold several keys — one per tool or integration is a good habit.

An admin creates keys in Settings → API Keys (name it, then Create key). If you are not an admin, ask one for a key. It looks like this:

wa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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 it (it stops working immediately) and create a new one.

2. Send it as a header

Every request carries the key in the X-API-Key header (Authorization: Bearer <key> works too):

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 under Contacts in Whatbot. Re-sending the same phone updates it — contacts are upserted by phone number.

Send the whole contact every time

An update replaces the contact’s name, tags, attributes and opt-in with what you send. A field you leave out is reset, not kept — and leaving out opt_in sets the contact back to pending, which drops them from opted-in broadcast audiences.

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.