{
  "openapi": "3.0.3",
  "info": {
    "title": "WaCentra Connect API",
    "version": "1.0.0",
    "description": "Connect a WhatsApp number and send messages from your own system. All requests and responses are JSON. Authenticate with a Bearer token obtained from POST /otp/verify, then send it as `Authorization: Bearer <token>`.",
    "contact": {
      "name": "WaCentra Connect API",
      "url": "https://wacentraconnectapi.com"
    }
  },
  "servers": [
    {
      "url": "/api/v1",
      "description": "Current environment"
    }
  ],
  "tags": [
    { "name": "Auth", "description": "Registration, login and one-time-password verification" },
    { "name": "Password", "description": "Password reset" },
    { "name": "Plans", "description": "Available packages" },
    { "name": "Account", "description": "The authenticated account" },
    { "name": "Subscriptions", "description": "Package subscriptions" },
    { "name": "Sessions", "description": "WhatsApp connection sessions" },
    { "name": "WhatsApp", "description": "Pairing, status and messages" }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API token"
      }
    },
    "schemas": {
      "ValidationError": {
        "type": "object",
        "properties": {
          "message": { "type": "string", "example": "The given data was invalid." },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": { "message": { "type": "string" } }
      },
      "OtpChallenge": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "purpose": { "type": "string", "enum": ["register", "login"] }
        }
      },
      "TokenResponse": {
        "type": "object",
        "properties": {
          "user": { "$ref": "#/components/schemas/User" },
          "token": { "type": "string" },
          "token_type": { "type": "string", "example": "Bearer" }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "email_verified_at": { "type": "string", "format": "date-time", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "subscription": { "$ref": "#/components/schemas/Subscription", "nullable": true }
        }
      },
      "Plan": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "price_cents": { "type": "integer" },
          "currency": { "type": "string" },
          "billing_interval": { "type": "string", "enum": ["week", "month", "year"] },
          "max_sessions": { "type": "integer", "nullable": true },
          "max_messages": { "type": "integer", "nullable": true },
          "trial_days": { "type": "integer" },
          "is_active": { "type": "boolean" }
        }
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "status": { "type": "string", "enum": ["trialing", "active", "past_due", "canceled", "expired"] },
          "starts_at": { "type": "string", "format": "date-time", "nullable": true },
          "trial_ends_at": { "type": "string", "format": "date-time", "nullable": true },
          "ends_at": { "type": "string", "format": "date-time", "nullable": true },
          "canceled_at": { "type": "string", "format": "date-time", "nullable": true },
          "plan": { "$ref": "#/components/schemas/Plan" }
        }
      },
      "Session": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "uuid": { "type": "string" },
          "device_name": { "type": "string", "nullable": true },
          "platform": { "type": "string", "nullable": true },
          "status": { "type": "string", "enum": ["active", "ended"] },
          "is_active": { "type": "boolean" },
          "subscription_id": { "type": "integer", "nullable": true },
          "started_at": { "type": "string", "format": "date-time", "nullable": true },
          "ended_at": { "type": "string", "format": "date-time", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "WhatsAppConnection": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["connecting", "qr", "open", "disconnected"] },
          "is_connected": { "type": "boolean" },
          "is_awaiting_pairing": { "type": "boolean" },
          "qr_code": { "type": "string", "nullable": true, "description": "PNG data URL", "example": "data:image/png;base64,iVBORw0KGgo..." },
          "phone_number": { "type": "string", "nullable": true },
          "display_name": { "type": "string", "nullable": true },
          "last_error": { "type": "string", "nullable": true },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "WhatsAppMessage": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "wa_message_id": { "type": "string", "nullable": true },
          "direction": { "type": "string", "enum": ["incoming", "outgoing"] },
          "type": { "type": "string", "enum": ["text", "image", "video", "document", "audio", "sticker", "gif", "contact", "location", "poll", "reaction", "view_once"] },
          "recipient": { "type": "string", "nullable": true },
          "body": { "type": "string", "nullable": true },
          "media": {
            "type": "object",
            "nullable": true,
            "properties": {
              "filename": { "type": "string", "nullable": true },
              "mime_type": { "type": "string", "nullable": true },
              "size": { "type": "integer", "nullable": true }
            }
          },
          "status": { "type": "string", "enum": ["pending", "sent", "delivered", "read", "failed"] },
          "error": { "type": "string", "nullable": true },
          "sent_at": { "type": "string", "format": "date-time", "nullable": true },
          "delivered_at": { "type": "string", "format": "date-time", "nullable": true },
          "read_at": { "type": "string", "format": "date-time", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid token",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }
      },
      "ValidationError": {
        "description": "Validation failed",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } }
      }
    }
  },
  "paths": {
    "/register": {
      "post": {
        "tags": ["Auth"],
        "summary": "Create an account and send a verification code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "password", "password_confirmation"],
                "properties": {
                  "name": { "type": "string", "maxLength": 255 },
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password" },
                  "password_confirmation": { "type": "string" },
                  "device_name": { "type": "string", "nullable": true }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Code sent",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpChallenge" } } }
          },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Verify credentials and send a login code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password" },
                  "device_name": { "type": "string", "nullable": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpChallenge" } } }
          },
          "403": { "description": "Account suspended" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/otp/verify": {
      "post": {
        "tags": ["Auth"],
        "summary": "Verify a register/login code and receive a token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "purpose", "code"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "purpose": { "type": "string", "enum": ["register", "login"] },
                  "code": { "type": "string", "example": "123456" },
                  "device_name": { "type": "string", "nullable": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verified",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } }
          },
          "403": { "description": "Account suspended" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/otp/resend": {
      "post": {
        "tags": ["Auth"],
        "summary": "Re-send a register/login/reset code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "purpose"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "purpose": { "type": "string", "enum": ["register", "login", "reset"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/password/forgot": {
      "post": {
        "tags": ["Password"],
        "summary": "Send a password-reset code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": { "email": { "type": "string", "format": "email" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Always returns the same message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/password/reset": {
      "post": {
        "tags": ["Password"],
        "summary": "Reset the password with a valid code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "code", "password", "password_confirmation"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "code": { "type": "string", "example": "123456" },
                  "password": { "type": "string", "format": "password" },
                  "password_confirmation": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/plans": {
      "get": {
        "tags": ["Plans"],
        "summary": "List active packages",
        "responses": {
          "200": {
            "description": "Plans",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } }
          }
        }
      }
    },
    "/plans/{slug}": {
      "get": {
        "tags": ["Plans"],
        "summary": "Show one package",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } },
          "404": { "description": "Not found" }
        }
      }
    },
    "/me": {
      "get": {
        "tags": ["Account"],
        "summary": "The authenticated user",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/logout": {
      "post": {
        "tags": ["Account"],
        "summary": "Revoke the current token",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/logout-all": {
      "post": {
        "tags": ["Account"],
        "summary": "Revoke every token",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Logged out everywhere", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/account": {
      "get": {
        "tags": ["Account"],
        "summary": "Account with usage summary",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Account",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": { "$ref": "#/components/schemas/User" },
                    "usage": {
                      "type": "object",
                      "properties": {
                        "active_sessions": { "type": "integer" },
                        "total_sessions": { "type": "integer" },
                        "subscriptions": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "patch": {
        "tags": ["Account"],
        "summary": "Update profile",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password", "nullable": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/subscriptions": {
      "get": {
        "tags": ["Subscriptions"],
        "summary": "List the user's subscriptions",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Subscriptions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Subscriptions"],
        "summary": "Activate a free package (paid packages require checkout)",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["plan_id"],
                "properties": { "plan_id": { "type": "integer" } }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "description": "Paid plan, or invalid plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }
        }
      }
    },
    "/subscriptions/{subscription}": {
      "get": {
        "tags": ["Subscriptions"],
        "summary": "Show a subscription",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "subscription", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } },
          "403": { "description": "Not yours" },
          "404": { "description": "Not found" }
        }
      }
    },
    "/subscriptions/{subscription}/cancel": {
      "post": {
        "tags": ["Subscriptions"],
        "summary": "Cancel a subscription",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "subscription", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } },
          "403": { "description": "Not yours" }
        }
      }
    },
    "/sessions": {
      "get": {
        "tags": ["Sessions"],
        "summary": "List connection sessions (paginated)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "ended"] } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated sessions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } },
                    "links": { "type": "object" },
                    "meta": { "type": "object" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Sessions"],
        "summary": "Start a session",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "device_name": { "type": "string" },
                  "platform": { "type": "string" },
                  "subscription_id": { "type": "integer", "nullable": true }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/sessions/{session}": {
      "get": {
        "tags": ["Sessions"],
        "summary": "Show a session",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "403": { "description": "Not yours" }
        }
      },
      "delete": {
        "tags": ["Sessions"],
        "summary": "Delete a session",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } },
          "403": { "description": "Not yours" }
        }
      }
    },
    "/sessions/{session}/end": {
      "post": {
        "tags": ["Sessions"],
        "summary": "End a session",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "403": { "description": "Not yours" }
        }
      }
    },
    "/sessions/{session}/whatsapp": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Connection state (and QR while pairing)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppConnection" } } } },
          "403": { "description": "Not yours" }
        }
      },
      "delete": {
        "tags": ["WhatsApp"],
        "summary": "Disconnect and unlink",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppConnection" } } } },
          "403": { "description": "Not yours" }
        }
      }
    },
    "/sessions/{session}/whatsapp/connect": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Start or resume pairing",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": { "description": "Pairing state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppConnection" } } } },
          "403": { "description": "Not yours" },
          "422": { "description": "Session not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }
        }
      }
    },
    "/sessions/{session}/whatsapp/messages": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "List messages (cursor paginated, newest first)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "direction", "in": "query", "schema": { "type": "string", "enum": ["incoming", "outgoing"] } },
          { "name": "type", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "sent", "delivered", "read", "failed"] } },
          { "name": "wa_message_id", "in": "query", "schema": { "type": "string" } },
          { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": {
          "200": {
            "description": "Paginated messages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppMessage" } },
                    "links": { "type": "object" },
                    "meta": { "type": "object" }
                  }
                }
              }
            }
          },
          "403": { "description": "Not yours" }
        }
      },
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a text message",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "text"],
                "properties": {
                  "to": { "type": "string", "description": "Phone number or group JID.", "example": "+254700000000" },
                  "text": { "type": "string", "maxLength": 4096 },
                  "mentions": { "type": "array", "maxItems": 100, "items": { "type": "string" }, "description": "Phone numbers or JIDs to mention in a group message." },
                  "reply_to": { "type": "string", "description": "WhatsApp message id to quote." },
                  "reply_to_from_me": { "type": "boolean", "default": true }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "403": { "description": "Not yours" },
          "422": { "description": "Not connected or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }
        }
      }
    },
    "/sessions/{session}/whatsapp/documents": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a PDF document (base64 encoded, 5 MB maximum)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "filename", "data"],
                "properties": {
                  "to": { "type": "string", "example": "+254700000000" },
                  "filename": { "type": "string", "example": "invoice-1042.pdf" },
                  "mime_type": { "type": "string", "enum": ["application/pdf"] },
                  "caption": { "type": "string", "maxLength": 1024 },
                  "data": { "type": "string", "description": "Base64 encoded PDF bytes." }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "403": { "description": "Not yours" },
          "422": { "description": "Not connected or invalid PDF", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }
        }
      }
    },
    "/sessions/{session}/whatsapp/messages/{message}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Show a single message",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "message", "in": "path", "required": true, "schema": { "type": "string", "description": "WhatsApp message id (wa_message_id); a local numeric id also works." } }
        ],
        "responses": {
          "200": { "description": "Message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "404": { "description": "Message not found for this session" }
        }
      },
      "delete": {
        "tags": ["WhatsApp"],
        "summary": "Revoke a message for everyone",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "message", "in": "path", "required": true, "schema": { "type": "string", "description": "WhatsApp message id." } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to"],
            "properties": {
              "to": { "type": "string", "example": "+254700000000" },
              "from_me": { "type": "boolean", "default": true }
            }
          } } }
        },
        "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/messages/{message}/edit": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Edit a sent text message",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "message", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "text"],
            "properties": {
              "to": { "type": "string" },
              "text": { "type": "string", "maxLength": 4096 },
              "from_me": { "type": "boolean", "default": true }
            }
          } } }
        },
        "responses": { "200": { "description": "Edited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/messages/read": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Mark inbound messages as read",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "message_ids"],
            "properties": {
              "to": { "type": "string" },
              "message_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }
            }
          } } }
        },
        "responses": { "200": { "description": "Read receipt sent" } }
      }
    },
    "/sessions/{session}/whatsapp/images": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send an image (base64, 5 MB maximum)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "filename", "data"],
            "properties": {
              "to": { "type": "string" },
              "filename": { "type": "string" },
              "mime_type": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp"] },
              "caption": { "type": "string", "maxLength": 1024 },
              "reply_to": { "type": "string" },
              "reply_to_from_me": { "type": "boolean", "default": true },
              "data": { "type": "string" }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } }
        }
      }
    },
    "/sessions/{session}/whatsapp/videos": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a video or GIF (base64, 16 MB maximum)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "filename", "data"],
            "properties": {
              "to": { "type": "string" },
              "filename": { "type": "string" },
              "mime_type": { "type": "string", "enum": ["video/mp4", "video/3gpp"] },
              "caption": { "type": "string", "maxLength": 1024 },
              "gif": { "type": "boolean", "default": false },
              "reply_to": { "type": "string" },
              "reply_to_from_me": { "type": "boolean", "default": true },
              "data": { "type": "string" }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } }
        }
      }
    },
    "/sessions/{session}/whatsapp/audio": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send audio or a voice note (base64, 16 MB maximum)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "filename", "data"],
            "properties": {
              "to": { "type": "string" },
              "filename": { "type": "string", "example": "voice-note.ogg" },
              "mime_type": { "type": "string", "enum": ["audio/ogg", "audio/opus", "audio/mp4", "audio/mpeg", "audio/aac", "audio/amr", "audio/webm"] },
              "voice_note": { "type": "boolean", "default": false },
              "data": { "type": "string" }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "422": { "description": "Not connected or invalid audio" }
        }
      }
    },
    "/sessions/{session}/whatsapp/view-once": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a view-once image, video or audio message (base64)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "type", "filename", "data"],
            "properties": {
              "to": { "type": "string", "example": "+254700000000" },
              "type": { "type": "string", "enum": ["image", "video", "audio"] },
              "filename": { "type": "string", "example": "photo.jpg" },
              "mime_type": { "type": "string", "enum": ["image/jpeg", "image/png", "image/webp", "video/mp4", "video/3gpp", "audio/ogg", "audio/opus", "audio/mp4", "audio/mpeg", "audio/aac", "audio/amr", "audio/webm"] },
              "caption": { "type": "string", "maxLength": 1024 },
              "reply_to": { "type": "string" },
              "reply_to_from_me": { "type": "boolean", "default": true },
              "data": { "type": "string", "description": "Base64 encoded media bytes. Images max 5 MB; videos and audio max 16 MB." }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "422": { "description": "Not connected or invalid media" }
        }
      }
    },
    "/sessions/{session}/whatsapp/stickers": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a WebP sticker (base64, 1 MB maximum)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "filename", "data"],
            "properties": {
              "to": { "type": "string" },
              "filename": { "type": "string", "example": "sticker.webp" },
              "mime_type": { "type": "string", "enum": ["image/webp"] },
              "data": { "type": "string" }
            }
          } } }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } },
          "422": { "description": "Not connected or invalid sticker" }
        }
      }
    },
    "/sessions/{session}/whatsapp/contacts": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "List contacts synced with the session",
        "description": "Contacts come from the session's history sync. An empty list with sync.complete set to false means the sync has not finished yet, not that there are no contacts. Use next_cursor as the cursor parameter to fetch the next page.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } },
          { "name": "cursor", "in": "query", "required": false, "description": "The next_cursor value from the previous page (a contact JID).", "schema": { "type": "string", "pattern": "^[0-9A-Za-z@._-]{1,80}$" } }
        ],
        "responses": { "200": { "description": "A page of contacts with total, next_cursor and sync.complete" } }
      },
      "put": {
        "tags": ["WhatsApp"],
        "summary": "Create or update a contact in the address book",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["phone"],
            "properties": {
              "phone": { "type": "string", "example": "+254700000000" },
              "first_name": { "type": "string", "maxLength": 100 },
              "last_name": { "type": "string", "maxLength": 100 },
              "full_name": { "type": "string", "maxLength": 200 }
            }
          } } }
        },
        "responses": { "200": { "description": "Contact saved" } }
      },
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send contact cards",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["to", "contacts"],
            "properties": {
              "to": { "type": "string" },
              "display_name": { "type": "string", "maxLength": 120 },
              "contacts": {
                "type": "array", "minItems": 1, "maxItems": 10,
                "items": { "type": "object", "required": ["name", "phone"], "properties": {
                  "name": { "type": "string", "maxLength": 120 },
                  "phone": { "type": "string" }
                } }
              }
            }
          } } }
        },
        "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/contacts/validate": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Check which numbers have a WhatsApp account",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["numbers"],
            "properties": { "numbers": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } } }
          } } }
        },
        "responses": { "200": { "description": "Validation results" } }
      }
    },
    "/sessions/{session}/whatsapp/contacts/{contact}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get contact details",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Contact details" } }
      }
    },
    "/sessions/{session}/whatsapp/contacts/{contact}/picture": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get a contact profile picture URL",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Profile picture URL (null when none is set)" } }
      }
    },
    "/sessions/{session}/whatsapp/contacts/{contact}/block": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Block a contact",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Contact blocked" } }
      }
    },
    "/sessions/{session}/whatsapp/contacts/{contact}/unblock": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Unblock a contact",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "contact", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Contact unblocked" } }
      }
    },
    "/sessions/{session}/whatsapp/lid-from-pn/{pn}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get the LID for a phone number",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "pn", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "LID mapping" },
          "404": { "description": "No mapping found" }
        }
      }
    },
    "/sessions/{session}/whatsapp/pn-from-lid/{lid}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get the phone number for a LID",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "lid", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Phone number mapping" },
          "404": { "description": "No mapping found" }
        }
      }
    },
    "/sessions/{session}/whatsapp/locations": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a location",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["to", "latitude", "longitude"],
            "properties": {
              "to": { "type": "string" },
              "latitude": { "type": "number", "minimum": -90, "maximum": 90 },
              "longitude": { "type": "number", "minimum": -180, "maximum": 180 },
              "name": { "type": "string", "maxLength": 255 },
              "address": { "type": "string", "maxLength": 255 }
            }
          } } }
        },
        "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/polls": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Send a poll",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["to", "name", "options"],
            "properties": {
              "to": { "type": "string" },
              "name": { "type": "string", "maxLength": 255 },
              "options": { "type": "array", "minItems": 2, "maxItems": 12, "items": { "type": "string", "maxLength": 100 } },
              "selectable_count": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1 }
            }
          } } }
        },
        "responses": { "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppMessage" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/reactions": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "React to a message (empty emoji removes it)",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["to", "message_id", "emoji"],
            "properties": {
              "to": { "type": "string" },
              "message_id": { "type": "string" },
              "emoji": { "type": "string", "maxLength": 8 },
              "from_me": { "type": "boolean", "default": false }
            }
          } } }
        },
        "responses": { "200": { "description": "Reaction sent" } }
      }
    },
    "/sessions/{session}/whatsapp/typing": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Set the typing indicator",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["to", "state"],
            "properties": {
              "to": { "type": "string" },
              "state": { "type": "string", "enum": ["composing", "paused"] }
            }
          } } }
        },
        "responses": { "200": { "description": "Presence updated" } }
      }
    },
    "/sessions/{session}/whatsapp/presence": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Set account presence",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["state"],
            "properties": { "state": { "type": "string", "enum": ["available", "unavailable"] } }
          } } }
        },
        "responses": { "200": { "description": "Presence updated" } }
      }
    },
    "/sessions/{session}/whatsapp/pause": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Pause a linked session without logging out",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppConnection" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/resume": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Resume a paused session",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppConnection" } } } } }
      }
    },
    "/sessions/{session}/whatsapp/groups": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "List every group the connected account participates in",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "List of groups" } }
      },
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Create a group",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["subject", "participants"],
            "properties": {
              "subject": { "type": "string", "maxLength": 100 },
              "participants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }
            }
          } } }
        },
        "responses": { "201": { "description": "Group created" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Fetch group metadata",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string", "example": "120363012345678901@g.us" } }
        ],
        "responses": { "200": { "description": "Group metadata" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/participants": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "List group participants",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Group participants" } }
      },
      "put": {
        "tags": ["WhatsApp"],
        "summary": "Promote or demote group participants",
        "description": "Same as the POST endpoint with action set to promote or demote.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["participants", "action"],
            "properties": {
              "participants": { "type": "array", "maxItems": 100, "items": { "type": "string" } },
              "action": { "type": "string", "enum": ["add", "remove", "promote", "demote"] }
            }
          } } }
        },
        "responses": { "200": { "description": "Participant update results" } }
      },
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Add, remove, promote or demote group participants",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["participants", "action"],
            "properties": {
              "participants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } },
              "action": { "type": "string", "enum": ["add", "remove", "promote", "demote"] }
            }
          } } }
        },
        "responses": { "200": { "description": "Participants updated" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/leave": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Leave a group",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Left group" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/invite": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Generate a group invite link",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Invite code and link" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/invite-link": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get a group invite link",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Invite code and link" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/picture": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get a group profile picture URL",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Group picture URL (null when none is set)" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/settings": {
      "put": {
        "tags": ["WhatsApp"],
        "summary": "Update group subject, description or settings",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "subject": { "type": "string", "maxLength": 100 },
              "description": { "type": "string", "maxLength": 512, "nullable": true },
              "announce": { "type": "boolean", "description": "Only admins can send messages" },
              "restrict": { "type": "boolean", "description": "Only admins can edit group settings" },
              "member_add_mode": { "type": "string", "enum": ["admin_add", "all_member_add"] },
              "join_approval": { "type": "boolean" }
            }
          } } }
        },
        "responses": { "200": { "description": "Updated group metadata" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/participants/add": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Add group participants",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["participants"],
            "properties": {
              "participants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }
            }
          } } }
        },
        "responses": { "200": { "description": "Participants added" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/participants/remove": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Remove group participants",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["participants"],
            "properties": {
              "participants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }
            }
          } } }
        },
        "responses": { "200": { "description": "Participants removed" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/{group}/reset": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Reset a group invite link",
        "description": "Revokes the current invite link and returns a new one. Existing links stop working. This does not clear the group's encryption keys.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "New invite code and link, with effect set to invite_link_revoked" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/invite/{code}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get group metadata from an invite code",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Group metadata" } }
      }
    },
    "/sessions/{session}/whatsapp/groups/invite/accept": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Accept a group invite code",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["code"],
            "properties": { "code": { "type": "string" } }
          } } }
        },
        "responses": { "200": { "description": "Group joined" } }
      }
    },
    "/sessions/{session}/whatsapp/communities": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "List communities the connected account participates in",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "List of communities" } }
      },
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Create a community",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["subject"],
            "properties": {
              "subject": { "type": "string", "maxLength": 100 },
              "description": { "type": "string", "maxLength": 512, "nullable": true }
            }
          } } }
        },
        "responses": { "201": { "description": "Community created" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/invite/{code}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Get community metadata from an invite code",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Community metadata" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/{community}": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "Fetch community metadata",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string", "example": "120363000000000001@g.us" } }
        ],
        "responses": { "200": { "description": "Community metadata" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/{community}/groups": {
      "get": {
        "tags": ["WhatsApp"],
        "summary": "List groups linked to a community",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Linked groups" } }
      },
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Link an existing group to a community",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["group"],
            "properties": { "group": { "type": "string", "example": "120363000000000002@g.us" } }
          } } }
        },
        "responses": { "200": { "description": "Group linked" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/{community}/groups/{group}": {
      "delete": {
        "tags": ["WhatsApp"],
        "summary": "Unlink a group from a community",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "group", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Group unlinked" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/{community}/groups/create": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Create a group inside a community",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["subject", "participants"],
            "properties": {
              "subject": { "type": "string", "maxLength": 100 },
              "participants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }
            }
          } } }
        },
        "responses": { "201": { "description": "Group created" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/{community}/settings": {
      "put": {
        "tags": ["WhatsApp"],
        "summary": "Update community subject or settings",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "subject": { "type": "string", "maxLength": 100 },
              "announce": { "type": "boolean" },
              "restrict": { "type": "boolean" }
            }
          } } }
        },
        "responses": { "200": { "description": "Updated community metadata" } }
      }
    },
    "/sessions/{session}/whatsapp/communities/{community}/leave": {
      "post": {
        "tags": ["WhatsApp"],
        "summary": "Leave a community",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "session", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "community", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Left community" } }
      }
    }
  }
}
