{
  "openapi": "3.0.3",
  "info": {
    "title": "Nexwapi Public API",
    "version": "1.0.0",
    "description": "WhatsApp Business messaging API. Authenticate with header `x-api-key` from Developer Settings.",
    "contact": { "name": "Nexwapi", "url": "https://nexwapi.com" }
  },
  "servers": [
    { "url": "https://api.nexwapi.com", "description": "Production" }
  ],
  "security": [{ "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string" }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "phone": { "type": "string" },
          "email": { "type": "string", "nullable": true },
          "tags": { "type": "array", "items": { "type": "string" } },
          "optedIn": { "type": "boolean" },
          "attributes": { "type": "object" },
          "chatStatus": { "type": "string" },
          "createdAt": { "type": "integer" }
        }
      }
    }
  },
  "paths": {
    "/api/v1/account": {
      "get": {
        "summary": "Get account",
        "responses": {
          "200": { "description": "Account info" },
          "401": { "description": "Invalid API key" }
        }
      }
    },
    "/api/v1/messages": {
      "post": {
        "summary": "Send WhatsApp message",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to"],
                "properties": {
                  "to": { "type": "string", "example": "919876543210" },
                  "text": { "type": "string" },
                  "template": { "type": "string" },
                  "params": { "type": "array", "items": { "type": "string" } },
                  "language": { "type": "string", "default": "en" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Message accepted" },
          "403": { "description": "Opted out / feature locked" },
          "402": { "description": "Insufficient credits" }
        }
      }
    },
    "/api/v1/contacts": {
      "get": {
        "summary": "List contacts",
        "parameters": [
          { "name": "phone", "in": "query", "schema": { "type": "string" } },
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25 } }
        ],
        "responses": { "200": { "description": "Contact list" } }
      },
      "post": {
        "summary": "Upsert contact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["phone"],
                "properties": {
                  "phone": { "type": "string" },
                  "name": { "type": "string" },
                  "email": { "type": "string" },
                  "tags": { "type": "array", "items": { "type": "string" } },
                  "optedIn": { "type": "boolean" },
                  "attributes": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Contact saved" } }
      }
    },
    "/api/v1/contacts/{phone}/opt-in": {
      "patch": {
        "summary": "Update opt-in",
        "parameters": [
          { "name": "phone", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["optedIn"],
                "properties": { "optedIn": { "type": "boolean" } }
              }
            }
          }
        },
        "responses": { "200": { "description": "Updated" } }
      }
    },
    "/api/v1/templates": {
      "get": {
        "summary": "List approved templates",
        "responses": { "200": { "description": "Templates" } }
      }
    },
    "/api/v1/events": {
      "post": {
        "summary": "Track a contact event",
        "description": "Track a registered custom or default event for an existing contact.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["event"],
                "properties": {
                  "event": { "type": "string" },
                  "phone": { "type": "string" },
                  "phone_number": { "type": "string" },
                  "userId": { "type": "string" },
                  "traits": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Event tracked" },
          "400": { "description": "Unknown event or validation error" },
          "404": { "description": "Contact not found" }
        }
      }
    }
  }
}