{
  "openapi": "3.0.3",
  "info": {
    "title": "Chatofy WhatsApp Business API & Platform Services",
    "description": "Official OpenAPI 3.0 specification for Chatofy platform services, contact inquiries, partner registrations, and automated messaging endpoints. Designed for developer integrations and LLM function calling.",
    "version": "1.0.0",
    "contact": {
      "name": "Chatofy Engineering & API Support",
      "email": "hello.chatofy@synbussolutions.com",
      "url": "https://chatofy.in/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://chatofy.in/terms"
    }
  },
  "servers": [
    {
      "url": "https://chatofy.in",
      "description": "Production Marketing & Public API Server"
    },
    {
      "url": "https://app.chatofy.in",
      "description": "Chatofy Dashboard & Cloud Application API Server"
    }
  ],
  "paths": {
    "/api/contact": {
      "post": {
        "summary": "Submit Contact or Enterprise Sales Inquiry",
        "description": "Submits a contact form or enterprise inquiry to Chatofy. Routes priority inquiries directly to solution architects.",
        "operationId": "submitContactInquiry",
        "tags": ["Public Inquiries"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactInquiryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry successfully submitted.",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input payload or missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/Retry-After" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server processing error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/partners": {
      "post": {
        "summary": "Apply for Agency or Reseller Partner Program",
        "description": "Registers an agency, systems integrator, or reseller applicant for Chatofy's revenue sharing partner program.",
        "operationId": "applyPartnerProgram",
        "tags": ["Partnership"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerApplicationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Partner application received.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid payload parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/messages/send": {
      "post": {
        "summary": "Send WhatsApp Message or Template",
        "description": "Dispatches a WhatsApp Cloud API text, media, or template message to a target phone number.",
        "operationId": "sendWhatsAppMessage",
        "tags": ["Messaging API"],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessageRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message queued or sent successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. Missing or invalid Bearer API Key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Self-throttle using Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/contacts": {
      "get": {
        "summary": "Retrieve Contacts List",
        "description": "Fetches contacts, tags, and custom metadata stored in your Chatofy multi-agent workspace.",
        "operationId": "getContactsList",
        "tags": ["Contacts API"],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of contacts to return (1-100).",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 100
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "Filter contacts by custom tag.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of contacts retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactsListResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Pass your Chatofy API key in the Authorization header: `Bearer ctf_live_...`"
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "Maximum requests allowed per window.",
        "schema": { "type": "integer", "example": 120 }
      },
      "RateLimit-Remaining": {
        "description": "Remaining requests in current window.",
        "schema": { "type": "integer", "example": 118 }
      },
      "RateLimit-Reset": {
        "description": "Seconds until rate limit window resets.",
        "schema": { "type": "integer", "example": 60 }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying when throttled (HTTP 429).",
        "schema": { "type": "integer", "example": 60 }
      }
    },
    "schemas": {
      "ContactInquiryRequest": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "example": "John Doe", "description": "Full name of the contact person." },
          "email": { "type": "string", "format": "email", "example": "john@company.com", "description": "Work email address." },
          "phone": { "type": "string", "example": "+91 9876543210", "description": "Phone number with country code." },
          "company": { "type": "string", "example": "Acme Technologies Ltd", "description": "Company or business name." },
          "inquiryType": { "type": "string", "example": "Sales & Enterprise", "description": "Category of inquiry." },
          "message": { "type": "string", "example": "We need WhatsApp automation for 100k conversations/month.", "description": "Detailed inquiry message." }
        }
      },
      "PartnerApplicationRequest": {
        "type": "object",
        "required": ["email", "partnershipType"],
        "properties": {
          "name": { "type": "string", "example": "Jane Smith" },
          "email": { "type": "string", "format": "email", "example": "jane@agency.com" },
          "agencyName": { "type": "string", "example": "Growth Media Agency" },
          "partnershipType": { "type": "string", "example": "Agency Reseller" },
          "message": { "type": "string", "example": "We manage 25 e-commerce clients interested in WhatsApp broadcasts." }
        }
      },
      "SendMessageRequest": {
        "type": "object",
        "required": ["to", "type"],
        "properties": {
          "to": { "type": "string", "example": "+917838343515", "description": "Recipient phone number with country code in E.164 format." },
          "type": { "type": "string", "enum": ["text", "template", "media"], "example": "text", "description": "Message payload type." },
          "message": { "type": "string", "example": "Hello! Your order #1042 has been shipped.", "description": "Text body if type is text." },
          "templateName": { "type": "string", "example": "order_update_v1", "description": "Meta approved template name if type is template." }
        }
      },
      "SendMessageResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "messageId": { "type": "string", "example": "msg_wam_992148" },
              "status": { "type": "string", "example": "sent" },
              "recipient": { "type": "string", "example": "+917838343515" }
            }
          },
          "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-23T01:07:44+05:30", "description": "ISO 8601 timestamp in IST (+05:30) format" }
        }
      },
      "ContactsListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "example": "cnt_1092" },
                "phone": { "type": "string", "example": "+917838343515" },
                "name": { "type": "string", "example": "Rahul Sharma" },
                "tags": { "type": "array", "items": { "type": "string" }, "example": ["VIP", "Shopify"] }
              }
            }
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "object" },
          "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-23T01:07:44+05:30", "description": "ISO 8601 timestamp in IST (+05:30) format" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string", "example": "INVALID_PAYLOAD", "description": "Machine-readable uppercase error identifier." },
              "message": { "type": "string", "example": "Name and Email are required fields.", "description": "Human-readable error description." },
              "hint": { "type": "string", "example": "Provide a valid JSON body with required parameters.", "description": "Actionable resolution guidance for developers and AI agents." },
              "timestamp": { "type": "string", "format": "date-time", "example": "2026-09-23T01:07:44+05:30", "description": "ISO 8601 timestamp in IST (+05:30) format" }
            }
          }
        }
      }
    }
  }
}