Barqia Developer API

Connect your platform to Barqia to send WhatsApp messages, approved templates and OTP codes over Meta's official API, and receive conversation events via webhooks. All endpoints live under /api/v1 and authenticate with an API key.

Authentication

Every send request authenticates with an API key starting with bqk_. A merchant generates it from the dashboard (Developers/API) — shown once. Pass it one of three ways:

# 1) Authorization header (recommended)
Authorization: Bearer bqk_xxxxxxxxxxxxxxxxxxxx

# 2) query string
https://barqia.net/api/v1/send-message?token=bqk_xxxx

# 3) in the JSON body  →  { "token": "bqk_xxxx", ... }

The API is a paid feature — it requires a plan that includes API access. Requests count against your message quota and respect opt-out.

Send endpoints

POST/api/v1/send-message

Send a plain text message (inside the 24h window).

curl -X POST https://barqia.net/api/v1/send-message \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "9665xxxxxxxx", "text": "أهلًا بك في متجرنا 👋" }'

Response

{ "success": true, "msg": "تم إرسال الرسالة", "messageId": "wamid.XXX" }

POST/api/v1/send_templet

Send an approved template (outside the 24h window). Variable count/order must match the approved template.

curl -X POST https://barqia.net/api/v1/send_templet \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "9665xxxxxxxx",
    "template_name": "barqia_booking_confirm",
    "language": "ar",
    "body_params": ["محمد", "خدمة التنظيف", "2026-07-01", "5:00 م"],
    "buttons": [{ "sub_type": "url", "index": 0, "parameter": "123" }]
  }'

Response

{ "success": true, "msg": "تم إرسال القالب", "messageId": "wamid.XXX" }

POST/api/v1/otp/send

Generate + send a 6-digit OTP via a template. 5-min TTL, with send throttles (per minute/hour/day). No template needed — it sends from Barqia's barqia_otp, provisioned on your number automatically. Pass template_name to use your own instead.

curl -X POST https://barqia.net/api/v1/otp/send \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "9665xxxxxxxx" }'

Response

{ "success": true, "msg": "تم إرسال رمز التحقق", "expiresInSeconds": 300 }

POST/api/v1/otp/verify

Verify the code. Max 5 attempts per code.

curl -X POST https://barqia.net/api/v1/otp/verify \
  -H "Authorization: Bearer bqk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "9665xxxxxxxx", "code": "123456" }'

Response

{ "success": true, "verified": true, "msg": "تم التحقق" }

Webhooks (inbound events)

Register an HTTPS URL from the dashboard to receive events. Each request is HMAC-SHA256 signed in the X-Barqia-Signature header so you can verify it.

message.received — inbound customer message
message.status — message status change (delivered/read/failed)
form.submitted — WhatsApp form submission

POST  https://your-server.com/webhook   (your registered URL)
X-Barqia-Event: message.received
X-Barqia-Signature: sha256=<hex_hmac_of_raw_body>

{ "chat_id": "...", "from": "9665xxxxxxxx", "name": "محمد",
  "type": "button", "text": "تأكيد", "button_payload": "CONFIRM_123",
  "meta_msg_id": "wamid.XXX" }

Verify the signature: HMAC-SHA256 of the raw body keyed by the secret (whsec_) shown once when you create the webhook.

Limits & notes

Global limit: 100 requests/minute per IP.
OTP: 60s cooldown + 5/hour + 20/day per number.
Numbers in international format without + (e.g. 9665xxxxxxxx).
Responses are always JSON; errors return success=false with msg.

Barqia Developer API

Authentication

Send endpoints

Webhooks (inbound events)

Limits & notes

Request API access / partnership