Recover Lead X — WhatsApp API

1) Overview

The Recover Lead X WhatsApp API lets you send and receive WhatsApp messages, manage media, use templates, and receive real‑time webhooks for inbound messages and delivery/read statuses.

• Base URL: https://api.recoverleadx.com/wa
• Auth header: X-RecoverleadX-API-Key: <key>
• Keys are issued by email to simplify onboarding.

2) Quickstart (5 minutes)

1. Find the key email: Subject “Your Recover Lead X API Key”. It contains the API key and the phone number it belongs to.
2. Set a webhook URL (recommended): Reply 200 OK within 5s. Use HTTPS.
3. Send your first message:

Copycurl -X POST https://api.recoverleadx.com/wa/messages   -H "X-RecoverleadX-API-Key: <YOUR_KEY_FROM_EMAIL>"   -H "Content-Type: application/json"   -d '{"messaging_product":"whatsapp","to":"+15551234567","type":"text","text":{"body":"Hello from Recover Lead X!"}}'

3) Authentication

• Header: X-RecoverleadX-API-Key: <key>
• Scope: One key per phone number.
• Rotation: Email support@recoverleadx.com; new key revokes the old one immediately.
• Storage: Use a secrets manager; never commit keys to code repos.

4) Base URL & Versioning

• Base: https://api.recoverleadx.com/wa
• Version header (optional): X-RecoverleadX-Version: 2025-10-01. If omitted, latest stable applies.

5) Messages API

POST /messages

Send text, media, template, or interactive messages. Use JSON and include your API key header.

Copy{"messaging_product":"whatsapp","to":"+15551234567","type":"text","text":{"body":"Your order is ready."}}

Template example

Copy{
  "messaging_product":"whatsapp",
  "to":"+15551234567",
  "type":"template",
  "template":{
    "name":"order_ready",
    "language":{"code":"en"},
    "components":[{"type":"body","parameters":[{"type":"text","text":"Alice"}]}]
  }
}

Typical success (201)

Copy{"messaging_product":"whatsapp","contacts":[{"input":"+15551234567","wa_id":"15551234567"}],"messages":[{"id":"wamid.HBgLM..."}]}

6) Media API

Upload

Copycurl -X POST https://api.recoverleadx.com/wa/media   -H "X-RecoverleadX-API-Key: <KEY>"   -F "messaging_product=whatsapp"   -F "file=@/path/file.jpg;type=image/jpeg"

Retrieve (short‑lived URL)

CopyGET /media/<media_id>

Delete

CopyDELETE /media/<media_id>

• Images ≤ 5 MB
• Audio ≤ 16 MB
• Video ≤ 16 MB
• Documents ≤ 100 MB
• Stickers: WEBP (static ≤100 KB, animated ≤500 KB)

7) Templates API

List

CopyGET /templates?limit=50&after=<cursor>

Create

Copy{
  "name":"order_ready",
  "category":"UTILITY",
  "language":"en",
  "components":[{"type":"BODY","text":"Hi {'{'}1{'}'}, your order is ready."}]
}

Delete

CopyDELETE /templates/order_ready?language=en

Status flow: PENDING_REVIEW → APPROVED | REJECTED (with reason).

8) Contacts API

Verify reachability

Copy{"blocking":"wait","contacts":["+15551234567","+15559876543"]}

Sample response

Copy{"messaging_product":"whatsapp","contacts":[{"input":"+15551234567","status":"valid"},{"input":"+15559876543","status":"invalid"}]}

9) Webhook Configuration

We can set your webhook for you, or configure via API.

Set phone‑number webhook

Copy{"url":"https://webhooks.example.com/rlx","secret":"<signing-secret>"}

Requirements: 200 OK within 5s • HTTPS • RFC‑compliant hostname (letters, digits, hyphens)

Delivery order: Phone‑number webhook (primary) → Account‑level webhook (fallback). If none configured, callbacks are not delivered.

10) Webhook Events & Security

• Events: messages, statuses, errors
• Headers: X-RecoverleadX-Timestamp, X-RecoverleadX-Signature
• Signature: sha256=HMAC_SHA256(secret, timestamp + '.' + raw_body)

Inbound text example

Copy{
  "object":"whatsapp_business_account",
  "entry":[{"id":"WABA_ID","changes":[{"field":"messages","value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"+15550001111","phone_number_id":"PHONE_NUMBER_ID"},"contacts":[{"profile":{"name":"Alice"},"wa_id":"15551234567"}],"messages":[{"from":"15551234567","id":"wamid.HBgLM...","timestamp":"1728512345","type":"text","text":{"body":"hi"}}]}}]}]
}

Verification (Node.js)

Copyimport crypto from "crypto";
export function isValidSignature(secret, timestamp, rawBody, header) {
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  return header === `sha256=${expected}`;
}

11) Errors

Copy{"error":{"code":"INVALID_API_KEY","message":"The API key is invalid or expired.","details":{}}}

• 400 INVALID_REQUEST — bad/missing fields
• 401 INVALID_API_KEY — wrong/revoked/mismatched key
• 403 ENDPOINT_BLOCKED — restricted access
• 429 RATE_LIMITED — apply backoff
• 500 SERVER_ERROR — retry with backoff

Media: repeated failed GET /media/<id> may temporarily block retrieval for that number.

12) Limits & Best Practices

• Default: 25 req/s per number; 100 req/s per account (soft).
• Webhook latency: respond within 5s; design for median < 250ms.
• 24‑hour window: free‑form messages inside; use templates outside.
• Idempotency: expect duplicate webhooks.
• Security: rotate keys periodically; never share keys in chat or tickets.

13) Key Management by Email

• Keys are generated by Recover Lead X and delivered to your registered email.
• We cannot retrieve old keys once rotated.
• If misplaced, email support@recoverleadx.com; we revoke the old key and email a new one.
• Optional: request a separate test key for staging.

14) Compliance

• Obtain explicit opt‑in before messaging users.
• Follow WhatsApp Business & Messaging policies for country/content rules.
• Avoid sensitive PII in message bodies; prefer short‑lived links.

15) Support & Status

• Email: support@recoverleadx.com
• Status page: (your preferred URL)
• SLA: define your response/resolution targets here if applicable.

16) Changelog

• 2025-10-16 — Email‑issued API keys clarified; single‑file page prepared.
• 2025‑10‑01 — Initial v1 release.