{"openapi":"3.1.0","info":{"title":"Falcon · Agent-Ready WhatsApp Platform","description":"A developer and AI agent communication platform for WhatsApp. Provides user OTP verification and transactional messaging through a simple REST API scoped by token quotas and instant kill switches.","version":"2.0.0","contact":{"name":"Phyr Studios","url":"https://phyr.in"}},"servers":[{"url":"https://falcon.phyr.in","description":"Falcon API Gateway"}],"paths":{"/otp/send":{"post":{"summary":"Send WhatsApp OTP","operationId":"sendWhatsAppOtp","description":"Generate a secure 6-digit one-time passcode and queue delivery over WhatsApp to the specified phone number. Enforces cooldown and quota checks.","security":[{"BearerAuth":[]},{"AppTokenHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"type":"string","description":"Recipient phone number with country code, digits only (8-16 digits).","example":"919876543210"},"channel":{"type":"string","enum":["whatsapp"],"default":"whatsapp","description":"Delivery channel. Only 'whatsapp' is supported."}},"required":["recipient"]}}}},"responses":{"202":{"description":"OTP queued for delivery","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Message queued for sending"},"agent_hint":{"type":"string","example":"The verification code has been dispatched. Ask the user to check their WhatsApp and provide the 6-digit code."}}}}}},"400":{"description":"Invalid recipient number or parameters"},"401":{"description":"Missing or invalid application token"},"429":{"description":"Cooldown active or WhatsApp quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"},"retry_after":{"type":"integer","example":45},"agent_hint":{"type":"string"}}}}}}}}},"/otp/validate":{"post":{"summary":"Validate WhatsApp OTP","operationId":"validateWhatsAppOtp","description":"Check the one-time passcode entered by the user. On success, invalidates the code and confirms authentication.","security":[{"BearerAuth":[]},{"AppTokenHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"type":"string","description":"Recipient phone number with country code, digits only.","example":"919876543210"},"passcode":{"type":"string","description":"The 4-8 digit verification code provided by the user.","example":"849201"}},"required":["recipient","passcode"]}}}},"responses":{"200":{"description":"Passcode authenticated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Passcode authenticated"},"agent_hint":{"type":"string","example":"Verification succeeded. Proceed with the authenticated user action."}}}}}},"400":{"description":"Invalid passcode or incorrect attempts","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid passcode"},"remainingAttempts":{"type":"integer","example":2},"agent_hint":{"type":"string"}}}}}},"429":{"description":"Too many failed attempts; passcode invalidated"}}}},"/message/send":{"post":{"summary":"Send Transactional WhatsApp Message","operationId":"sendWhatsAppMessage","description":"Send a direct transactional text message to a user over WhatsApp. Subject to token yearly quota caps.","security":[{"BearerAuth":[]},{"AppTokenHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"type":"string","description":"Recipient phone number with country code, digits only.","example":"919876543210"},"message":{"type":"string","maxLength":500,"description":"Text message content to deliver (up to 500 characters).","example":"Your appointment has been confirmed for 3:00 PM."}},"required":["recipient","message"]}}}},"responses":{"200":{"description":"Message delivered / queued","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Message queued for sending"},"agent_hint":{"type":"string","example":"Message has been sent to the user on WhatsApp."}}}}}},"429":{"description":"Yearly quota exceeded for this agent token"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Provide your Falcon application token in the standard HTTP Authorization header: `Authorization: Bearer <TOKEN>`."},"AppTokenHeader":{"type":"apiKey","in":"header","name":"x-app-token","description":"Alternative header: provide your Falcon application token via `x-app-token: <TOKEN>`."}}}}