Skip to main content

Automate account setup

Most people sign up and link a number in the dashboard (see the Quickstart). This page is for when you want to do it from code instead — for example, to create accounts and instances for your own customers, or to script a setup.

Two steps always need a person, because they involve their own email and phone: clicking the login link in their email, and scanning the QR code with WhatsApp. Everything else can be automated.

1. Create the account​

curl -X POST https://app.tarceel.com/auth/request-link \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "Jane Doe", "phone": "+15551234567", "mode": "signup"}'

This always returns 202. The person receives an email with a login link. Following it (GET /auth/verify?token=...) returns an account token:

{ "token": "<jwt>" }

2. Get a long-lived token for your scripts​

The account token expires after 30 days, and getting a new one needs a login link again. For anything automated, create a personal access token once and use that instead — it never expires until you revoke it.

curl -X POST https://app.tarceel.com/account/tokens \
  -H "Authorization: Bearer <account token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "setup script"}'

Use the returned pat_... value anywhere an account token works. See Authentication for what each credential can do.

3. Create an instance​

curl -X POST https://app.tarceel.com/instances \
  -H "Authorization: Bearer <account token or pat_...>" \
  -H "Content-Type: application/json" \
  -d '{"billingMode": "prepaid", "name": "Customer A"}'
{ "instanceId": "clx1234...", "apiKey": "sk_..." }

Save the apiKey now — it's only shown once. During the free trial a tenant can have one instance; see Billing.

The person who owns the number has to scan a QR code. The QR endpoint returns the QR data, which you render as an image in your own UI:

curl https://app.tarceel.com/instances/<instanceId>/qr -H "Authorization: Bearer sk_..."

Poll it until the code appears and keep refreshing — WhatsApp rotates it every few seconds. Once they've scanned it, GET /instances/<instanceId> reports "sessionStatus": "connected".

If you'd rather not build a QR screen, send them to https://app.tarceel.com/dashboard/instances/<instanceId>, which shows it for them.

Connecting another app instead​

If you're building an integration (an ERP, CRM or similar) and want your users to link their own instance with one click, use Connect. It hands your app an instance id and key without anyone copy-pasting them.