=====================================================================
  WhatsApp Call Verification - website demo (version 1.0)
=====================================================================

WHAT IT DOES
  Your visitor types their WhatsApp number, taps "Call on WhatsApp" and
  calls your WhatsApp business number. We pick up, play a short message
  and hang up. The number is verified. No code to type, no SMS.

WHAT IS IN THIS FOLDER
  index.html          The page your visitor sees.
  wa-call-verify.php  Your API key and all settings. The page talks ONLY
                      to this file. This file talks to the API.
  README.txt          This guide.

WHAT YOU NEED
  - A website that opens with https:// and runs PHP 7.4 or newer
    (with the curl and openssl extensions - almost every host has them).
  - Your API key: Dashboard -> Profile -> API Key.
  - A WhatsApp number on your account with calling switched on.
  - A phone with WhatsApp, to test.


---------------------------------------------------------------------
  PART A - SET IT UP (about 5 minutes)
---------------------------------------------------------------------

STEP 1 - Open the settings
  Open wa-call-verify.php in any text editor (Notepad is fine).
  All settings are at the top, inside $WCV_CONFIG = [ ... ].

STEP 2 - Paste your API key
      'api_key' => 'PASTE_YOUR_API_KEY_HERE',
  Put your key between the quotes, like this:
      'api_key' => '923001234567-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',

STEP 3 - Choose how numbers get verified
      'verify_mode' => 'both',
    'auto'   = Automatic. The page says "verified" by itself.
               It checks every few seconds (STEP 6).
    'manual' = With a Verify button. The visitor calls, comes back
               and taps "I have called - Verify".
    'both'   = The visitor can choose. Good for testing.

STEP 4 - Optional: your webhook address (instant Automatic mode)
  A webhook is the address where the API tells your server "this
  number is verified". It is THIS PHP file + ?action=webhook:
      'webhook_url' => 'https://your-domain.com/verify/wa-call-verify.php?action=webhook&t=LONG-RANDOM-SECRET',
  Rules: https only, port 443 or 8443, a real public address, no
  login page or redirect in front of it.
  Make it safer (recommended):
    - &t=LONG-RANDOM-SECRET : make up any long random text. Webhooks
      without exactly this secret are refused.
    - 'webhook_allowed_ips' => ['188.245.210.139'],
      Only the API's server may send webhooks to this file.
  Every webhook must also carry a valid signature (made with your
  API key) and be less than 10 minutes old.
  Leave it empty ('') and Automatic mode still works: the PHP file
  asks the API at every check (STEP 6) instead of waiting for a webhook.
  NOTE: the API refuses webhook addresses on the service's own
  websites (a safety rule). Use your own website's address.

STEP 5 - Time to call (optional)
      'time_limit_minutes' => 5,
  How long the visitor has to make the call: 1 to 5 minutes.
  Default: 5. The circle timer on the page follows this setting.

STEP 6 - How often to check (optional)
      'check_every_seconds' => 5,
  Automatic mode: how often the page checks for the result, from 2 to
  30 seconds. Default: 5. Smaller = "Number verified" shows sooner
  (e.g. 2); bigger = fewer requests to your server (e.g. 10).

STEP 7 - Upload both files into ONE folder
  For example public_html/verify/ :
      public_html/
      +-- verify/
          +-- index.html
          +-- wa-call-verify.php
  The PHP file makes a small private folder "wa-call-verify-data"
  next to it for counters and a log. Better: set 'data_dir' to a
  folder OUTSIDE public_html (needed on Nginx servers).

STEP 8 - Check the setup
  Open in your browser:
      https://your-domain.com/verify/wa-call-verify.php?action=ping
  You want to see:   "ready": true
  If not, the "problems" list says exactly what to fix.
  It also tests your webhook address for you.

  Something wrong and you want details? Set 'debug' => true, try
  again, and every error shows the API's exact reply. Set it back
  to false before you go live. Your key is never shown.


---------------------------------------------------------------------
  PART B - TRY IT WITH YOUR PHONE
---------------------------------------------------------------------

STEP 9 - Open the page on your phone
      https://your-domain.com/verify/index.html
  Type your WhatsApp number in international format:
  country code + number, no + and no 0 at the start.
      Pakistan: 923001234567      UAE: 971501234567
  Choose Automatic or Verify button (only shown when 'both').
  Tap "Start verification".

STEP 10 - Call on WhatsApp
  A circle timer starts (5 minutes by default) and fills up as the
  time passes. Tap the green "Call on WhatsApp" button: WhatsApp opens
  with a call to your business number. Make the call FROM THE NUMBER
  YOU TYPED. We pick up, play a short message and hang up.
  On a computer? Use WhatsApp on your phone to call the number shown
  (WhatsApp Desktop cannot make this call).

STEP 11 - Verified
  Automatic: the page shows "Number verified" by itself, normally
             at its next check after we pick up (STEP 6).
  Verify button: go back to the page and tap
             "I have called - Verify".

STEP 12 - Save the number on your side
  In wa-call-verify.php, find the function on_number_verified().
  It runs ONCE, right after a number is verified, with the number
  the API confirmed. Put your own code there, for example:
      UPDATE users SET phone = ?, phone_verified = 1 WHERE id = ?
  Use YOUR login/session to know which of your users is asking.


---------------------------------------------------------------------
  WHY NOBODY CAN FAKE "VERIFIED"
---------------------------------------------------------------------
  - Your API key stays in the PHP file on your server. It is never
    sent to the page or the phone.
  - The page only gets a sealed "ticket" (AES-256-GCM). It cannot
    read or change it. Change one letter and it stops working.
  - A ticket only works in the browser that started it (a private
    cookie). A copied ticket is useless anywhere else.
  - Webhooks must carry a valid X-SENDPK-Signature, made with YOUR
    API key. A fake or changed webhook is refused (HTTP 401).
  - With &t=SECRET in webhook_url and webhook_allowed_ips set, a
    webhook must also know the secret and come from the API's
    server. An old webhook (over 10 minutes) cannot be sent again.
    A real webhook for a request this file did not start is ignored.
  - Even a real webhook is only a "wake up": before saying
    verified, the PHP file asks the API itself (status.php) with
    your key, and checks it is the SAME request and the SAME number.
  - on_number_verified() runs only once per request.
  - The page cannot say "verified" by itself. Changing the page code
    in the browser changes nothing on your server.
  - The caller must call FROM the typed number: WhatsApp tells us
    who is calling. A call from another number does not count.
  - Limits stop abuse: 5 starts per number a day, 10 per visitor an
    hour, 300 checks per visitor in 10 minutes (change them in the
    settings). Pages on other websites cannot use your PHP file.
  - The data folder holds no phone numbers (only masked ones in the
    log) and is closed to browsers.


---------------------------------------------------------------------
  QUESTIONS
---------------------------------------------------------------------
  "Verification is not available right now"
      Open ?action=ping (STEP 8). Most often: the API key, or no
      balance. Turn on 'debug' for the exact reason.

  Automatic mode says "not available" (debug shows INVALID_CALLBACK_URL)
      The API refused your webhook_url. Check STEP 4 and the ping, or
      leave webhook_url empty: Automatic then works without a webhook.

  The page waits but never says verified (Automatic)
      Even without webhooks, the PHP file asks the API every 15
      seconds, so it still finishes. If it never does: make sure the
      call came from the typed number and WhatsApp showed "connected".

  "Too many tries"
      A limit was reached. Wait, or change the limit_* settings.

  Can I change the look?
      Yes. Change index.html as you like (colors are at the top in
      :root). Keep the two files in the same folder, or change
      BRIDGE at the top of the script in index.html.

  Mobile app (Android / iPhone)?
      Use the same PHP file. Your app sends the same requests as
      index.html (start, check, cancel) and keeps cookies, or set
      'bind_to_browser' => false.

  Full API documentation: open the WhatsApp Call Verification API
  page on your dashboard website (whatsapp_call_verification_api.php).
