{
  "openapi": "3.0.3",
  "info": {
    "title": "DripChat Bot API",
    "version": "2026-10-18",
    "description": "Official outbound text and native video API. Authenticate with the full bot token in the path. Not the Telegram API or a personal access token API."
  },
  "servers": [
    {
      "url": "https://api.dripchat.io"
    }
  ],
  "externalDocs": {
    "url": "https://api.dripchat.io/docs/bots"
  },
  "paths": {
    "/bot{token}/getMe": {
      "get": {
        "operationId": "getMe",
        "summary": "Check bot identity and sending capabilities without sending a message",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full secret bot token (including colon), loaded from secure storage. Never log token-bearing URLs."
          }
        ],
        "responses": {
          "200": {
            "description": "Bot identity, supported_methods and private_chat_addressing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BotResult"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bot{token}/sendMessage": {
      "post": {
        "operationId": "sendMessage",
        "summary": "Send a text message",
        "description": "Private recipients do not need to message the bot first. Use chat_id=@username or recipient_id. Existing group membership and blocks are enforced. No AI credits are consumed.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full secret bot token (including colon), loaded from secure storage. Never log token-bearing URLs."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 121,
              "pattern": "^[A-Za-z0-9_:@-]+$"
            },
            "description": "Unique per intended send. Persist and reuse for identical retries. Do not reuse across methods, recipients, or different content. Reserved names __proto__, constructor, prototype are invalid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Canonical field names; see guide for compatibility aliases. Supply exactly one destination.",
                "properties": {
                  "chat_id": {
                    "type": "string",
                    "description": "@username, me (bot owner), or an existing member chat ID",
                    "example": "@ikako"
                  },
                  "recipient_id": {
                    "type": "string",
                    "description": "Exact DripChat user ID"
                  },
                  "recipient_username": {
                    "type": "string",
                    "description": "Exact username, optionally prefixed with @"
                  },
                  "reply_to_message_id": {
                    "type": "string"
                  },
                  "operationId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "clientMessageId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096
                  }
                },
                "required": [
                  "text"
                ],
                "oneOf": [
                  {
                    "required": [
                      "chat_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_username"
                    ]
                  }
                ]
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "description": "Canonical field names; see guide for compatibility aliases. Supply exactly one destination.",
                "properties": {
                  "chat_id": {
                    "type": "string",
                    "description": "@username, me (bot owner), or an existing member chat ID",
                    "example": "@ikako"
                  },
                  "recipient_id": {
                    "type": "string",
                    "description": "Exact DripChat user ID"
                  },
                  "recipient_username": {
                    "type": "string",
                    "description": "Exact username, optionally prefixed with @"
                  },
                  "reply_to_message_id": {
                    "type": "string"
                  },
                  "operationId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "clientMessageId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096
                  }
                },
                "required": [
                  "text"
                ],
                "oneOf": [
                  {
                    "required": [
                      "chat_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_username"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message stored; delivery queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResult"
                }
              }
            }
          },
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Access denied or blocked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Recipient not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency or destination conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Previous message removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Upload too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Busy; retry identical request with the same key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry with the same key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bot{token}/sendVideo": {
      "post": {
        "operationId": "sendVideo",
        "summary": "Send a native playable video",
        "description": "Private recipients do not need to message the bot first. Use chat_id=@username or recipient_id. Existing group membership and blocks are enforced. No AI credits are consumed.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Full secret bot token (including colon), loaded from secure storage. Never log token-bearing URLs."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 121,
              "pattern": "^[A-Za-z0-9_:@-]+$"
            },
            "description": "Unique per intended send. Persist and reuse for identical retries. Do not reuse across methods, recipients, or different content. Reserved names __proto__, constructor, prototype are invalid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chat_id": {
                    "type": "string",
                    "description": "@username, me (bot owner), or an existing member chat ID",
                    "example": "@ikako"
                  },
                  "recipient_id": {
                    "type": "string",
                    "description": "Exact DripChat user ID"
                  },
                  "recipient_username": {
                    "type": "string",
                    "description": "Exact username, optionally prefixed with @"
                  },
                  "reply_to_message_id": {
                    "type": "string"
                  },
                  "operationId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "clientMessageId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "video": {
                    "type": "string",
                    "format": "uri",
                    "description": "Direct public HTTPS MP4/MOV URL. Not a social page URL."
                  },
                  "caption": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "width": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 8192
                  },
                  "height": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 8192
                  },
                  "duration": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 86400
                  },
                  "supports_streaming": {
                    "type": "boolean"
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "chat_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_username"
                    ]
                  }
                ],
                "required": [
                  "video"
                ],
                "description": "Canonical field names. Supply one destination; width and height must appear together. Compatibility aliases are described in the guide."
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "chat_id": {
                    "type": "string",
                    "description": "@username, me (bot owner), or an existing member chat ID",
                    "example": "@ikako"
                  },
                  "recipient_id": {
                    "type": "string",
                    "description": "Exact DripChat user ID"
                  },
                  "recipient_username": {
                    "type": "string",
                    "description": "Exact username, optionally prefixed with @"
                  },
                  "reply_to_message_id": {
                    "type": "string"
                  },
                  "operationId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "clientMessageId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "video": {
                    "type": "string",
                    "format": "uri",
                    "description": "Direct public HTTPS MP4/MOV URL. Not a social page URL."
                  },
                  "caption": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "width": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 8192
                  },
                  "height": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 8192
                  },
                  "duration": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 86400
                  },
                  "supports_streaming": {
                    "type": "boolean"
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "chat_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_username"
                    ]
                  }
                ],
                "required": [
                  "video"
                ],
                "description": "Canonical field names. Supply one destination; width and height must appear together. Compatibility aliases are described in the guide."
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "chat_id": {
                    "type": "string",
                    "description": "@username, me (bot owner), or an existing member chat ID",
                    "example": "@ikako"
                  },
                  "recipient_id": {
                    "type": "string",
                    "description": "Exact DripChat user ID"
                  },
                  "recipient_username": {
                    "type": "string",
                    "description": "Exact username, optionally prefixed with @"
                  },
                  "reply_to_message_id": {
                    "type": "string"
                  },
                  "operationId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "clientMessageId": {
                    "type": "string",
                    "maxLength": 121
                  },
                  "video": {
                    "type": "string",
                    "format": "binary",
                    "description": "MP4/MOV, at most 26214400 bytes; H.264/HEVC with optional AAC audio."
                  },
                  "caption": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "width": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 8192
                  },
                  "height": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 8192
                  },
                  "duration": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 86400
                  },
                  "supports_streaming": {
                    "type": "boolean"
                  }
                },
                "oneOf": [
                  {
                    "required": [
                      "chat_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_id"
                    ]
                  },
                  {
                    "required": [
                      "recipient_username"
                    ]
                  }
                ],
                "required": [
                  "video"
                ],
                "description": "Canonical field names. Supply one destination; width and height must appear together. Compatibility aliases are described in the guide."
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Message stored; delivery queued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResult"
                }
              }
            }
          },
          "200": {
            "description": "Idempotent replay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Access denied or blocked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Recipient not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency or destination conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Previous message removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Upload too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Busy; retry identical request with the same key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retry with the same key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error_code",
          "description"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error_code": {
            "type": "integer"
          },
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "SendResult": {
        "type": "object",
        "required": [
          "ok",
          "result",
          "replay"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "replay": {
            "type": "boolean"
          },
          "result": {
            "type": "object",
            "required": [
              "message_id",
              "chatId",
              "type"
            ],
            "properties": {
              "message_id": {
                "type": "string"
              },
              "chatId": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "text",
                  "video"
                ]
              },
              "videoURL": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      },
      "BotResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "result": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "is_bot": {
                "type": "boolean"
              },
              "first_name": {
                "type": "string"
              },
              "username": {
                "type": "string"
              },
              "supported_methods": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "can_initiate_private_chats": {
                "type": "boolean"
              },
              "private_chat_addressing": {
                "type": "object"
              },
              "documentation_url": {
                "type": "string",
                "format": "uri"
              },
              "openapi_url": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}