{ "openapi": "3.1.0", "info": { "title": "WAppOTP API", "version": "1.0.0", "description": "QR-linked WhatsApp OTP, transactional messaging, consent and campaign API. API keys are project-scoped and permission-scoped." }, "servers": [ { "url": "https://api.yourdomain.com" } ], "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "wa_live_...", "description": "Project API key. Grant only the scopes required by the integration." }, "PublishableSiteKey": { "type": "http", "scheme": "bearer", "bearerFormat": "wa_pk_...", "description": "Publishable browser OTP key. Requests must include an Origin header matching the key's configured allowed origins." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Recommended for send/create requests. Reusing the same key with the same request replays the original response." }, "ClientIp": { "name": "X-WhatsAppOTP-Client-IP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "For trusted server-side proxies only. Forward the original visitor IP so OTP abuse limits apply per end user instead of the proxy server." } }, "schemas": { "SendOtpRequest": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "examples": [ "+639171234567" ] }, "connectionId": { "type": "string" }, "template": { "type": "string", "description": "Optional text template containing {{code}}." } } }, "SendOtpResponse": { "type": "object", "properties": { "verificationId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "examples": [ "pending" ] }, "expiresIn": { "type": "integer", "examples": [ 300 ] } } }, "VerifyOtpRequest": { "type": "object", "required": [ "verificationId", "code" ], "properties": { "verificationId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } } }, "MessageRequest": { "type": "object", "required": [ "to", "text" ], "properties": { "to": { "type": "string" }, "text": { "type": "string", "maxLength": 4000 }, "connectionId": { "type": "string" } } }, "ConsentRequest": { "type": "object", "required": [ "phone", "status", "source" ], "properties": { "phone": { "type": "string" }, "status": { "type": "string", "enum": [ "OPTED_IN", "OPTED_OUT" ] }, "source": { "type": "string" }, "evidence": { "type": "string" }, "name": { "type": "string" } } }, "CampaignRequest": { "type": "object", "required": [ "name", "text", "recipients" ], "properties": { "name": { "type": "string" }, "text": { "type": "string", "maxLength": 4000 }, "recipients": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string" } }, "connectionId": { "type": "string" }, "media": { "$ref": "#/components/schemas/CampaignMedia" } } }, "MediaMessageRequest": { "type": "object", "required": [ "to", "type", "url" ], "properties": { "to": { "type": "string" }, "type": { "type": "string", "enum": [ "IMAGE", "VIDEO", "DOCUMENT" ] }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS media URL. Redirects and private/reserved network destinations are rejected by the worker." }, "caption": { "type": "string", "maxLength": 1024 }, "filename": { "type": "string", "maxLength": 255, "description": "Required when type is DOCUMENT." }, "mimeType": { "type": "string", "maxLength": 100 }, "connectionId": { "type": "string" } } }, "CampaignMedia": { "type": "object", "required": [ "type", "url" ], "properties": { "type": { "type": "string", "enum": [ "IMAGE", "VIDEO", "DOCUMENT" ] }, "url": { "type": "string", "format": "uri", "description": "Public HTTPS media URL." }, "filename": { "type": "string", "maxLength": 255, "description": "Required for DOCUMENT." }, "mimeType": { "type": "string", "maxLength": 100 } } }, "MessageStatus": { "type": "string", "enum": [ "QUEUED", "SENDING", "SENT", "DELIVERED", "READ", "FAILED", "BLOCKED" ] }, "MessageResult": { "type": "object", "required": [ "id", "kind", "toE164", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "OTP", "TRANSACTIONAL", "CAMPAIGN" ] }, "toE164": { "type": "string" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "mediaType": { "anyOf": [ { "type": "string", "enum": [ "IMAGE", "VIDEO", "DOCUMENT" ] }, { "type": "null" } ] }, "mediaUrl": { "type": [ "string", "null" ] }, "mediaFilename": { "type": [ "string", "null" ] }, "mediaMimeType": { "type": [ "string", "null" ] }, "providerMessageId": { "type": [ "string", "null" ] }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "security": [ { "ApiKey": [] } ], "paths": { "/v1/otp/send": { "post": { "summary": "Send an OTP", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientIp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOtpRequest" } } } }, "responses": { "200": { "description": "OTP accepted", "headers": { "x-request-id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOtpResponse" } } } }, "402": { "description": "Plan limit reached" }, "409": { "description": "Idempotency conflict" }, "429": { "description": "Rate limit exceeded" } }, "x-required-scope": "otp:send" } }, "/v1/otp/verify": { "post": { "summary": "Verify an OTP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpRequest" } } } }, "responses": { "200": { "description": "Verification result" }, "404": { "description": "Verification not found" } }, "x-required-scope": "otp:verify" } }, "/v1/messages": { "post": { "summary": "Send a transactional WhatsApp message", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "200": { "description": "Message queued" }, "402": { "description": "Plan limit reached" }, "409": { "description": "Idempotency conflict" }, "429": { "description": "Rate limit exceeded" } }, "x-required-scope": "messages:send" } }, "/v1/messages/{messageId}": { "get": { "summary": "Get message status", "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Message status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } } }, "404": { "description": "Message not found" } }, "x-required-scope": "messages:read" } }, "/v1/consents": { "post": { "summary": "Record or update recipient consent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentRequest" } } } }, "responses": { "200": { "description": "Consent saved" } }, "x-required-scope": "consents:write" }, "get": { "summary": "List consent records", "responses": { "200": { "description": "Consent list" } }, "x-required-scope": "consents:read" } }, "/v1/campaigns": { "post": { "summary": "Create a consent-gated campaign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRequest" } } } }, "responses": { "200": { "description": "Campaign queued" }, "400": { "description": "Consent or suppression validation failed" }, "402": { "description": "Plan limit reached" }, "409": { "description": "Idempotency conflict" } }, "x-required-scope": "campaigns:write" }, "get": { "summary": "List campaigns", "responses": { "200": { "description": "Campaign list" } }, "x-required-scope": "campaigns:read" } }, "/v1/campaigns/{id}": { "get": { "summary": "Get campaign status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign details" }, "404": { "description": "Campaign not found" } }, "x-required-scope": "campaigns:read" } }, "/v1/messages/media": { "post": { "summary": "Send an image, video, or document message", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaMessageRequest" } } } }, "responses": { "200": { "description": "Media message queued" }, "400": { "description": "Invalid URL, media type, or document metadata" }, "402": { "description": "Plan limit reached" }, "409": { "description": "Idempotency conflict" }, "429": { "description": "Rate limit exceeded" } }, "x-required-scope": "messages:send" } }, "/v1/browser/otp/send": { "post": { "summary": "Send OTP from browser using a publishable site key", "security": [ { "PublishableSiteKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOtpRequest" } } } }, "responses": { "200": { "description": "OTP queued" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked site key" }, "402": { "description": "Plan limit reached" }, "403": { "description": "Origin not allowed" }, "429": { "description": "Rate limit exceeded" } } } }, "/v1/browser/otp/verify": { "post": { "summary": "Verify browser OTP using a publishable site key", "security": [ { "PublishableSiteKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpRequest" } } } }, "responses": { "200": { "description": "Verification result" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or revoked site key" }, "403": { "description": "Origin not allowed" } } } }, "/v1/campaigns/{id}/cancel": { "post": { "summary": "Cancel a queued campaign", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign cancelled and unsent queued recipients blocked" }, "400": { "description": "Completed campaign cannot be cancelled" }, "404": { "description": "Campaign not found" } }, "x-required-scope": "campaigns:write" } } }, "x-api-key-scopes": { "otp:send": "Send OTP codes", "otp:verify": "Verify OTP codes", "messages:send": "Send transactional messages", "messages:read": "Read message delivery state", "consents:read": "Read consent records", "consents:write": "Create/update consent records", "campaigns:read": "Read campaign state", "campaigns:write": "Create campaigns" } }