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