{
  "openapi": "3.1.0",
  "info": {
    "title": "Thikaa Messaging API",
    "description": "Official REST API for Thikaa — the multimodal AI chatbot platform for MENA. Send and receive messages on WhatsApp, Telegram, Facebook Messenger, Instagram and TikTok from your own systems. Incoming messages are delivered to your webhook, signed with HMAC-SHA256. Available on Professional and Enterprise plans. Human docs (Arabic + English, curl examples): https://thikaa.com/docs/api.php",
    "version": "1.0.0",
    "contact": {
      "name": "Thikaa Support",
      "email": "support@thikaa.com",
      "url": "https://thikaa.com"
    }
  },
  "servers": [
    {
      "url": "https://thikaa.com/{store}/api/messaging",
      "description": "Per-tenant production API — {store} is your store slug shown in your dashboard URL",
      "variables": {
        "store": { "default": "your-store", "description": "Your Thikaa store/tenant slug" }
      }
    }
  ],
  "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getStatus",
        "summary": "Instance status",
        "description": "Returns the API key's instance status, allowed channels and current credit balance. Pass ?action=status.",
        "parameters": [
          { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": ["status"] } }
        ],
        "responses": {
          "200": {
            "description": "Status payload",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "ok": { "type": "boolean" },
                "instance_id": { "type": "string" },
                "channels": { "type": "array", "items": { "type": "string" } },
                "balance": { "type": "number" }
              } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "sendMessage",
        "summary": "Send a message",
        "description": "Send a text (optionally with media) to a customer on any connected channel. Pass ?action=send. Messages consume your normal credits. Rate limit: 60 requests/minute per key by default.",
        "parameters": [
          { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": ["send"] } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "required": ["channel", "to", "message"],
            "properties": {
              "channel": { "type": "string", "enum": ["wd", "wa", "tg", "fb", "ig", "tt"], "description": "wd=WhatsApp (QR), wa=WhatsApp Official API, tg=Telegram, fb=Messenger, ig=Instagram, tt=TikTok" },
              "to": { "type": "string", "description": "Phone number with country code (WhatsApp) or platform user id" },
              "message": { "type": "string", "description": "UTF-8 text — Arabic fully supported" },
              "media_url": { "type": "string", "format": "uri", "description": "Optional public HTTPS URL of an image/document" },
              "media_type": { "type": "string", "description": "Optional hint, e.g. image or document" }
            } } } }
        },
        "responses": {
          "200": {
            "description": "Message accepted",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "ok": { "type": "boolean" },
                "message_id": { "type": "string" },
                "channel": { "type": "string" },
                "to": { "type": "string" }
              } } } }
          },
          "400": { "description": "Missing/invalid fields (e.g. missing_channel)" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "description": "insufficient_balance — account inactive or out of credit" },
          "403": { "description": "channel_not_allowed for this key, or plan_not_eligible (requires Professional/Enterprise)" },
          "429": { "description": "Per-key rate limit exceeded (default 60/minute)" }
        }
      }
    }
  },
  "webhooks": {
    "incomingMessage": {
      "post": {
        "operationId": "incomingMessageWebhook",
        "summary": "Incoming customer message (delivered to YOUR webhook URL)",
        "description": "Configure a webhook URL per API key in the dashboard's Messaging API page. Each inbound customer message on the key's channels is POSTed as JSON. Verify authenticity with the X-Thikaa-Signature header: sha256=HMAC_SHA256(raw_body, webhook_secret).",
        "parameters": [
          { "name": "X-Thikaa-Event", "in": "header", "schema": { "type": "string", "example": "message.received" } },
          { "name": "X-Thikaa-Signature", "in": "header", "schema": { "type": "string", "example": "sha256=<hmac-hex>" } }
        ],
        "requestBody": {
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "event": { "type": "string" },
              "instance_id": { "type": "string" },
              "data": { "type": "object" }
            } } } }
        },
        "responses": { "200": { "description": "Acknowledge receipt" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer <api_key> — create keys from the dashboard's Messaging API page" },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "responses": {
      "Unauthorized": { "description": "missing_api_key or invalid_api_key" }
    }
  },
  "externalDocs": {
    "description": "Human-readable docs (Arabic + English) with curl and signature-verification samples",
    "url": "https://thikaa.com/docs/api.php"
  }
}