{
  "openapi": "3.1.0",
  "info": {
    "title": "ArabyBot WhatsApp OTP API",
    "version": "1.0.0",
    "description": "Send a one-time verification code to a phone number over WhatsApp, then verify it. This is ArabyBot's public developer API as it runs today. Create an OTP app in the dashboard (app.arabybot.com → OTP) to get its public key (ab_otp_…) and secret (sk_otp_…, shown once). Each code goes out as a Meta-approved authentication template, billed at Meta's authentication rate for the recipient's country — from your own WhatsApp number, or from ArabyBot's shared sender number charged to your wallet. Sending other WhatsApp messages (an approved template or a 24-hour text) is the send API at https://app.arabybot.com/api/v1 (key from Developer tools). Docs: https://arabybot.com/guides/whatsapp-otp-api",
    "contact": {
      "name": "ArabyBot Support",
      "email": "support@arabybot.com",
      "url": "https://arabybot.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://app.arabybot.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "PublicKey": []
    }
  ],
  "tags": [
    {
      "name": "OTP",
      "description": "Send, verify, resend and check WhatsApp verification codes"
    }
  ],
  "paths": {
    "/wa_otp_api/send": {
      "post": {
        "tags": [
          "OTP"
        ],
        "operationId": "sendOtp",
        "summary": "Send a verification code",
        "description": "Generates a numeric code and sends it to the phone over WhatsApp. Keep the returned request_id; you verify against it, never against the phone number.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Signature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendRequest"
              },
              "example": {
                "phone": "966501234567",
                "lang": "ar",
                "length": 6,
                "expiry_seconds": 300,
                "metadata": {
                  "user_id": "u_1042"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                }
              }
            }
          },
          "401": {
            "description": "missing_key, invalid_key, missing_signature or bad_signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "package_expired, module_not_entitled, subscription_expired, quota_exceeded or insufficient_balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "origin_blocked, ip_blocked or pool_access_denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "missing_phone or invalid_phone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limit_phone, cooldown, rate_limit_app, rate_limit_app_day, pool_daily_cap or pool_min_gap — see retry_after",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "wa_send_failed — WhatsApp refused the send; a shared-sender charge is refunded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "pool_unavailable or pool_disabled (shared sender only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wa_otp_api/verify": {
      "post": {
        "tags": [
          "OTP"
        ],
        "operationId": "verifyOtp",
        "summary": "Verify a code",
        "description": "Checks the code the user typed against the request. A code verifies once; a wrong code returns attempts_remaining.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Signature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyRequest"
              },
              "example": {
                "request_id": "3f6c2a9e-41b7-4c0d-9a51-7e2b8d4f1c60",
                "code": "482913"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          },
          "401": {
            "description": "invalid_code (with attempts_remaining), or an authentication error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "expired or already_resolved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "missing_fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "too_many_attempts — request a new code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wa_otp_api/resend": {
      "post": {
        "tags": [
          "OTP"
        ],
        "operationId": "resendOtp",
        "summary": "Resend a code",
        "description": "Sends a fresh code for an existing request, under the same rate limits as send. Every resend is a new billed WhatsApp message.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Signature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "request_id"
                ],
                "properties": {
                  "request_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResponse"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "missing_request_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "a rate limit — see retry_after",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wa_otp_api/status/{request_id}": {
      "get": {
        "tags": [
          "OTP"
        ],
        "operationId": "otpStatus",
        "summary": "Check a request's status",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "missing_request_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wa_otp_api/ping": {
      "get": {
        "tags": [
          "OTP"
        ],
        "operationId": "ping",
        "summary": "Check your key and read the app's settings",
        "responses": {
          "200": {
            "description": "The app behind the key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PingResponse"
                }
              }
            }
          },
          "401": {
            "description": "missing_key or invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PublicKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Public-Key",
        "description": "The OTP app's public key (ab_otp_…). Never put the secret in a browser."
      }
    },
    "parameters": {
      "Signature": {
        "name": "X-Signature",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "example": "sha256=5d41402abc4b2a76b9719d911017c592…"
        },
        "description": "Required only when the app has request signing switched on: sha256=<hex HMAC-SHA256 of the exact raw request body, keyed with the app secret>."
      }
    },
    "schemas": {
      "SendRequest": {
        "type": "object",
        "required": [
          "phone"
        ],
        "properties": {
          "phone": {
            "type": "string",
            "description": "International format, digits only or with a leading +, e.g. 966501234567. Egyptian local numbers (01…) are also accepted."
          },
          "lang": {
            "type": "string",
            "description": "Template language code, e.g. ar or en. Defaults to the app's language."
          },
          "length": {
            "type": "integer",
            "minimum": 4,
            "maximum": 8,
            "description": "Code length. Never shorter than the app's own setting."
          },
          "expiry_seconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 900,
            "description": "How long the code stays valid. Defaults to the app's setting."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Your own key/values, stored with the request."
          }
        }
      },
      "SendResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds"
          },
          "expires_at": {
            "type": "string",
            "description": "Server time, Y-m-d H:i:s"
          }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": [
          "request_id",
          "code"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "VerifyResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": true
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "phone": {
            "type": "string"
          },
          "verified_at": {
            "type": "string"
          }
        }
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "description": "pending, verified, expired, consumed or failed"
          },
          "attempts": {
            "type": "integer"
          },
          "expires_at": {
            "type": "string"
          },
          "verified_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PingResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "app_name": {
            "type": "string"
          },
          "brand_name": {
            "type": "string"
          },
          "platform_type": {
            "type": "string"
          },
          "default_lang": {
            "type": "string"
          },
          "code_length": {
            "type": "integer"
          },
          "expiry_seconds": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error_code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds, on 429"
          },
          "attempts_remaining": {
            "type": "integer",
            "description": "On invalid_code"
          }
        }
      }
    }
  },
  "x-webhook": {
    "description": "If the app has a callback URL, a verified code is POSTed to it as {event: 'otp.verified', app_id, request_id, phone, verified_at} with headers X-ArabyBot-Event and X-ArabyBot-Signature: sha256=<hex HMAC-SHA256 of the raw body keyed with the app secret>."
  }
}
