Skip to main content

Quickstart

From signup to a sent WhatsApp message in about five minutes. You'll use the dashboard for the two steps that need a person (signing up and scanning a QR code), then call the API for everything else.

Free trial, no card needed

New accounts start with a free trial. You can send real messages right away, before entering any payment details. See Billing for what happens when it ends.

1. Sign up​

Open the dashboard, choose Sign up, and enter your name, email and phone number. There's no password — we email you a one-time link, and clicking it signs you in.

  1. In the dashboard, click Add instance and give it a name. An instance is one linked WhatsApp number.
  2. Open the instance and scan the QR code with WhatsApp on your phone: Settings → Linked devices → Link a device.
  3. The status at the top of the page changes to Connected.

3. Copy your credentials​

On the instance's Overview tab, the Credentials card shows two values. Copy both:

  • Instance ID — identifies this number in every API URL.
  • API key (starts with sk_) — your server sends it as Authorization: Bearer sk_....
caution

The API key is shown once, when it's created. If you lose it, use Generate a new one — the old key stops working immediately.

4. Send your first message​

Replace INSTANCE_ID and sk_... with your values, and 15551234567 with a real number (country code and digits, no +) that has WhatsApp and has agreed to receive your message.

curl -X POST https://app.tarceel.com/instances/INSTANCE_ID/messages/text \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "15551234567", "text": "Hello from Tarceel!"}'

A successful call returns a message id straight away:

{ "id": "clx9876..." }

Sending is asynchronous — the message is queued and sent within moments. Check how it's going with that id:

curl https://app.tarceel.com/instances/INSTANCE_ID/messages/clx9876.../status \
  -H "Authorization: Bearer sk_..."
{ "id": "clx9876...", "status": "delivered" }

The status moves through pending → sent → delivered → read (or failed).

If you get an error instead, the most common ones are 409 (the number isn't connected — check the instance status in the dashboard) and 402 (out of trial or credit — see Billing).

5. Receive replies​

To get inbound messages and delivery updates on your own server, give the instance a webhook URL:

curl -X PUT https://app.tarceel.com/instances/INSTANCE_ID/webhook \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.example.com/tarceel-webhook"}'

The response includes a signing secret — save it, it's only shown once. Tarceel then POSTs a signed JSON event to your URL whenever something happens, for example an incoming message:

{
  "id": "cly9876...",
  "event": "message.received",
  "instanceId": "clx1234...",
  "timestamp": 1730000000000,
  "data": { "id": "3EB0...", "from": "15551234567@s.whatsapp.net", "type": "text", "text": "Hi!" }
}

See Webhooks for every event, how to verify the signature, and how retries work.

Prefer to try it in the browser?​

Every instance's dashboard page has a Try the API tab: pick an operation, fill a small form, and it generates the equivalent request in cURL, Node.js, Python, PHP, Java or C#/.NET with your real instance id and key already filled in. A Send test request button fires it for real.

Where to go next​

  • Sending Messages — media, locations and contact cards, with examples.
  • Webhooks — events, signatures and retries.
  • Authentication — the three credential types and what each is for.
  • Automate account setup — create accounts and instances from code, with no dashboard.
  • Connect — pair a third-party app with one click, no copied key.
  • API Reference — every route, generated from our OpenAPI spec.