Konekla — WhatsApp & OTP API for Haiti

Quickstart

Apre ou siyen sou tablodebò a, ale nan Settings → API Keys epi jenere yon kle. Kle a parèt yon sèl fwa — sere l. Mete l ansanm ak Business-X-Id ou nan headers chak rekèt.

first-message

curl -X POST https://konekla.com/api/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "Business-X-Id: <YOUR_BUSINESS_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "to": "50937123456",
    "body": "Bonjou! Mèsi pou kòmand ou."
  }'

Authentication

Tout rekèt mande de headers. Yon kle ki gen yon Business-X-Id ki pa koresponn ap retounen 403.

Header	Valè
Business-X-Id	UUID biznis ou (depi tablodebò)
Authorization	Bearer <your-api-key>
Content-Type	application/json

Pa janm ekspoze kle a sou frontend. Toujou apèl la depi sèvè a. Si yon kle konpwomi, revoke l imedyatman depi tablodebò a.

Phone numbers

API a aksepte sèlman nimewo Ayisyen pou voye mesaj. Format E.164 san siy plus, 11 chif total.

Aksepte

50937123456
50932123456
50922123456

Pa aksepte

+509 37 12 34 56 (siy plus, espas)
37123456 (san kòd peyi)
15551234567 (US)

Anvan ou voye, retire espas, tirè, parantèz, ak +. Si nimewo a pa valid, API a retounen 400 invalid_phone.

POST/api/whatsapp/send

Voye yon mesaj WhatsApp transactional. Itilize li pou konfimasyon kòmand, rapèl, mesaj sipò.

Body

`to`required	`string`	Nimewo Ayisyen, 11 chif kòmanse ak 509.
`body`required	`string`	Tèks mesaj la (1–4096 karaktè). Sipòte Unicode (Kreyòl, Fransè, emoji).
`typing_time`	`number`	Segond ki similar 'k ap tape' anvan livrezon. 0–30. Default: 0.

curl -X POST https://konekla.com/api/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "Business-X-Id: <YOUR_BUSINESS_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "to": "50937123456",
    "body": "Mèsi pou kòmand ou! Liv sou wout: KMD-9182.",
    "typing_time": 0
  }'

Repons (200)

{
  "ok": true,
  "id": "msg_01HXYZ...",
  "status": "queued"
}

POST/api/whatsapp/otp/send

Jenere yon kòd OTP, sere li sou sèvè ak yon TTL kout, epi voye li sou WhatsApp itilizatè a. Aplikasyon ou pa janm wè kòd la.

Body

phoneNumberrequired string Nimewo destinatè a (11 chif, 509...).

curl -X POST https://konekla.com/api/whatsapp/otp/send \
  -H "Content-Type: application/json" \
  -H "Business-X-Id: <YOUR_BUSINESS_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{ "phoneNumber": "50937123456" }'

Voye OTP la apre itilizatè a rive sou paj verifikasyon an, pa anvan. Sa redui chans pou kòd la ekspire avan li tape li.

POST/api/whatsapp/otp/verify

Verifye kòd 6 chif itilizatè a tape. Apre yon verifikasyon ki pase, kòd la otomatikman envalide.

Body

`phoneNumber`required	`string`	Menm nimewo a ki te resevwa OTP la.
`code`required	`string`	Kòd 6 chif itilizatè a tape.

curl -X POST https://konekla.com/api/whatsapp/otp/verify \
  -H "Content-Type: application/json" \
  -H "Business-X-Id: <YOUR_BUSINESS_ID>" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{
    "phoneNumber": "50937123456",
    "code": "123456"
  }'

Repons (200)

{
  "ok": true,
  "verified": true
}

Egzanp konplè (login flow)

// Full login flow with Konekla OTP
async function startLogin(phone) {
  await call("/api/whatsapp/otp/send", { phoneNumber: phone });
}

async function completeLogin(phone, code) {
  const res = await call("/api/whatsapp/otp/verify", {
    phoneNumber: phone,
    code
  });
  return res.ok && res.verified;
}

async function call(path, body) {
  const r = await fetch(`https://konekla.com${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Business-X-Id": process.env.KONEKLA_BUSINESS_ID,
      "Authorization": `Bearer ${process.env.KONEKLA_KEY}`
    },
    body: JSON.stringify(body)
  });
  return r.json();
}

Errors

Tout repons erè swiv menm fòm: yon code ki estab pou debugage pwogramatik, ak yon message pou itilizatè final.

{
  "ok": false,
  "code": "invalid_phone",
  "message": "Haitian numbers must be 8 digits (or 11 digits starting with 509)"
}

Status	Code	Sa pou fè
401	missing_business_id · missing_bearer · invalid_token · unknown_key · revoked	Tcheke headers yo. Si kle a revoke, jenere yon nouvo.
403	business_mismatch	Business-X-Id pa koresponn ak kle a. Itilize Business-X-Id ki nan tablodebò ou.
400	invalid_json · invalid_input · invalid_phone	Tcheke fòma body a, valè champs yo, ak fòma nimewo a.
404	no_account	Pa gen kont pou nimewo sa. Itilize signup.
402	insufficient_credits	Achte plis kredi nan paj Billing.
429	rate_limited	Backoff exponensyèl. Pa retry nan boukle sere.
5xx	upstream_5xx · upstream_unreachable	Retry ak backoff (max 3 fwa). Si pèsiste, tcheke status page.

Credits & pricing

Chak apèl ki reyisi (send, otp/send, otp/verify) konsome 1 kredi. Si yon apèl echwe (erè validasyon, upstream timeout), kredi a otomatikman rambouse.

Plan free

10 / jou

Reset chak 00h00 UTC

Pri pa kredi

1 HTG

Achte ak MonCash

Achte minimòm

10 kredi

Pa gen ekspirasyon

Apre 10 kredi gratis yo fini, apèl yo retounen 402 insufficient_credits jiskaske ou achte plis nan paj Billing. Repons sak reyisi yo gen yon champ credits.source "free" | "paid" pou suiv.

Rate limits

Yon token bucket per-biznis pèmèt rafal jiska 10 rekèt/segond, ki rifil 1 token chak segond. Lè limit la depase, w ap jwenn yon 429 rate_limited ak yon champ retry_after_ms.

Pou voye anpil mesaj an batch (kanpay, blast), itilize backoff eksponansyèl, oswa kontakte nou pou yon rate ki pi wo.

Best practices

Pa janm logue kòd OTP
Ni nan log app ou, ni nan monitwaring, ni nan tikè sipò. Si yon log expoze kòd la, sistèm OTP la pèdi tout valè li.
Voye OTP apre paj verifikasyon an chaje
TTL la kout pou yon rezon. Voye kòd la lè itilizatè a deja sou ekran ki ap tann li.
Lokalize body mesaj yo
Itilizatè ayisyen yo espere Kreyòl oswa Fransè. Mesaj an angle sèlman fè konvèsyon ou tonbe.
Mask nimewo nan log
Itilize 509***12345 olye nimewo konplè. Konfòmite avèk pwoteksyon done.
Toujou pran konsantman
Pa voye mesaj broadcast san itilizatè a opt-in. Règ WhatsApp pi sere pase SMS.
Sere ID mesaj retounen yo
Pou flow ki gen anpil enpòtans, sere ID a pou trace pita.

Pare pou kòmanse?

Jenere kle ou jodi a, voye premye mesaj ou nan kèk minit.

Kreye kont