A REST API on api/v1
Clean JSON endpoints under /api/v1. Everything you do in the dashboard, you do programmatically with the same IDs.
Build on WIDERS
An official REST API, keys with permission scopes, and signed webhooks. Everything you see in the platform is available programmatically. Stable public IDs (public_id) and a WidersApps signature on every request.
public_id · ULIDIdempotency-KeyX-RateLimit-*User-Agent: WidersApps/1.0
Overview
One predictable API: JSON, cursor pagination, and living documentation.
Cursor pagination
Stable pages via ?limit&cursor, with next_cursor and has_more in the response, and no duplicates.
An OpenAPI spec
Living OpenAPI docs and an interactive reference. Explore every endpoint and try it directly.
Live & Test keys
Create production (wa_live_) or test (wa_test_) keys, and switch mode with the X-Widers-Mode header.
Authentication
Authentication & scopes
Personal access keys passed in the Authorization: Bearer header. Scopes are the platform's own permission names, so a key never exceeds its owner.
Request header
Attach your key on every request. A test key starts with wa_test_.
Authorization: Bearer wa_live_<id>|<token>
wa_live_ · production wa_test_ · test
Scopes
Grant each key the least it needs, with no wildcards and no excess privilege.
contacts.viewcontacts.manageinbox.accesstags.managequick-replies.managecommerce.viewcommerce.managecampaigns.viewcampaigns.managecalendar.viewcalendar.manage
Examples
Your first request in a minute
Read your contacts with a single GET request. The response is wrapped in data and meta for the cursor.
api/v1 · GET /contacts
$ curl https://console.widers.net/api/v1/contacts?limit=25 \ -H "Authorization: Bearer wa_live_<id>|<token>" \ -H "Accept: application/json" # 200 OK · application/json { "data": [ { "public_id": "01J8ZKP7Q3M9XR2VH4B6TCDA5E", "name": "Maha Q.", "channel": "whatsapp", "tags": ["vip"] } ], "meta": { "next_cursor": "eyJ0IjoiYyJ9", "has_more": true } }
Illustrative response
Resources
Everything in the platform, programmatically
The same resources you manage from the dashboard, each governed by an explicit scope.
Contacts
Read, create and update contacts, unified by phone, with tags and custom fields.
contacts.view · contacts.manage
Conversations & messages
Read the unified inbox and send replies across your channels, with stable IDs.
inbox.access
Tags
Create tags and apply them to contacts and conversations programmatically.
tags.manage
Campaigns
Launch WhatsApp campaigns with approved templates, and read delivery results.
campaigns.view · campaigns.manage
Store, products & orders
Read the catalog, and create orders and update their statuses from your system.
commerce.view · commerce.manage
Calendar & bookings
Read availability, and create and cancel bookings through a unified API.
calendar.view · calendar.manage
Webhooks
Instant, signed events
Register a receiver and choose your events. We POST a JSON payload the moment they happen, signed with HMAC.
Subscribable topics
order.createdorder.paidinvoice.paidcontact.createdcontact.taggedconversation.createdconversation.closedbooking.createdbooking.cancelledcampaign.completed
Automatic retries on delivery failure, until your endpoint receives the event.
Signature verification computed as HMAC-SHA256 against the raw, unparsed body, within a replay time window.
A safe public URL accepts public receivers over HTTPS only, and rejects internal addresses (SSRF protection).
The signed header
Every payload we send carries a time-stamped signature:
X-Widers-Signature: t=1706342400,v1=<hmac_sha256>
HMAC-SHA256 time-stamped
Ready now
Integrations built on the same API
No need to build from scratch. Connect your tools today, and extend with the API as you grow.
ZapierGoogle SheetsSallaZid
Start now
Create your key, and fire your first request
Activate an API key with specific scopes, and read the interactive docs. Everything's ready to try.