Core concepts
The handful of ideas that everything else builds on: workspaces, sandbox vs live, the prepaid balance, templates, and how billing works.
Read this once and the rest of the docs will click into place. None of these concepts are complicated — but knowing them up front saves a lot of guessing.
Workspaces & accounts
A workspace (also called an account) is the top-level container for everything you do on Darkel: your prepaid balance, your connected WhatsApp number, your templates, your message history, your team, and your API keys.
Each workspace has a short public ID — an 8-character code shown in the dashboard. Quote it when you contact support so we can find your account quickly.
- You can belong to more than one workspace (for example, your own and a client’s).
- Everything is scoped to a single workspace — data never leaks between them.
- You can invite teammates and give each a role that controls what they can see and do (see Team & permissions).
Sandbox vs live
Every live workspace can spin up a free sandbox — a paired, isolated copy for testing. Build against the sandbox, then go live with confidence.
One base URL for everyone
There is a single API host — https://api.darkel.ng — used by both sandbox and live. You never switch URLs. The API key you send decides the environment: a dk_test_ key acts on your sandbox, a dk_live_ key acts on your live workspace.
| Sandbox | Live | |
|---|---|---|
| Recipients | A small allow-list of approved test numbers | Any opted-in customer |
| Charges | Play money — nothing real is billed | Real prepaid balance |
| API key | dk_test_… | dk_live_… |
| WhatsApp number | A shared Darkel test number | Your own number, or a shared one |
| Base URL | https://api.darkel.ng | https://api.darkel.ng |
Because the only difference is the credential, promoting from test to production is a one-line change: swap your dk_test_ key for a dk_live_ key. No URLs, no flags, no rebuild.
Sandbox recipient limit
In the sandbox you can only message numbers on the approved test list. Sending to anything else is rejected before it reaches WhatsApp, with a clear error. The dashboard shows the current list; ask us to add more test numbers if you need them.
Prepaid balance
Darkel is pay-as-you-go. You top up a prepaid balance, and each message is charged at Meta’s price for it. There are no monthly surprises — when the balance runs low, you top up again.
- Top up by card or bank transfer (Paystack), or instantly with play money in the sandbox.
- A message is charged when it is accepted for sending, at Meta’s price for its type and the recipient’s country, converted to naira at Darkel’s published rate. No markup — see the price list.
- Once Meta confirms how a message was billed, the charge is corrected automatically: a different type adjusts the difference, a free or failed message is refunded in full.
- Sending on your own number has no per-message charge from Darkel; Meta bills you directly.
- Set a low-balance threshold and we email you before you run out.
Internally, amounts are tracked in kobo (₦1 = 100 kobo). The dashboard always shows friendly Naira figures; you only meet kobo if you read raw amounts from the API.
Products & enrolment
A product is a capability you switch on for a workspace — WhatsApp messaging is the main one. Enrolling activates the feature and may carry a small recurring access fee in addition to the per-message price.
- Access fee — an optional monthly or yearly charge to keep the product active.
- Message price — Meta’s price for each message, charged as you send on a Darkel number.
- If a renewal cannot be paid because the balance is too low, the product pauses (sending stops) until you top up — your data and templates are untouched.
Live pricing for any product is public — see Billing & pricing or fetch it via the API.
Message templates
WhatsApp only lets businesses start conversations using templates that Meta has reviewed and approved. Darkel follows this rule: every message you send names an approved template and supplies its variables.
- Utility — transactional messages like order updates and reminders.
- Marketing — promotions and offers.
- Authentication — one-time passcodes (OTPs); Meta writes the wording and you just supply the code.
Because sends are template-only, your message always delivers regardless of WhatsApp’s 24-hour customer-service window. Plan your messaging around templates from day one — see Templates.
Team & permissions
Invite teammates to a workspace and assign each a role. Roles are made of fine-grained permissions, so you can let someone send messages without giving them access to billing, for example.
- Owner — full access, including billing and team management.
- Member / Viewer — built-in roles with narrower access.
- Custom roles — build your own from the available permissions.
Invited people join by signing in with the invited email (password or Google). Manage all of this under Workspace → Team in the dashboard.
Dashboard vs API
Two surfaces, one account:
| Surface | Who uses it | Auth | Typical actions |
|---|---|---|---|
| Dashboard | People on your team | Email/Google sign-in | Connect a number, create templates, top up, invite teammates, send by hand |
| API | Your backend | X-Api-Key header | Send messages automatically, read live pricing |
They share the same balance, number and templates. Set things up once in the dashboard, then let your code send through the API. Details in Authentication.