### Install Telegram Approver using Go (Bash)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Installs the telegram-approver binary using Go's install command. This requires Go version 1.25.5 or later. The command fetches the latest version from the specified GitHub repository.

```bash
# Requires Go >= 1.25.5
go install github.com/codex-k8s/telegram-approver/cmd/telegram-approver@latest
```

--------------------------------

### Run Telegram Approver Service (Bash)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Starts the telegram-approver service with minimal configuration using long polling mode. It requires setting the Telegram bot token and chat ID as environment variables. An example with voice transcription support is also provided, which includes installing ffmpeg.

```bash
# Minimal configuration (long polling mode)
export TG_APPROVER_TOKEN="your-bot-token"
export TG_APPROVER_CHAT_ID="your-chat-id"
telegram-approver

# With voice transcription support
export TG_APPROVER_TOKEN="your-bot-token"
export TG_APPROVER_CHAT_ID="your-chat-id"
export TG_APPROVER_OPENAI_API_KEY="sk-..."
sudo apt-get install -y ffmpeg  # Required for voice normalization
telegram-approver
```

--------------------------------

### Install telegram-approver using Go

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Installs the telegram-approver command-line tool using Go's package management. Requires Go version 1.25.5 or higher.

```bash
go install github.com/codex-k8s/telegram-approver/cmd/telegram-approver@latest
```

--------------------------------

### Create and Run Telegram Approval Service (Go)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

This Go code snippet demonstrates how to initialize and run the Telegram Approver service. It loads configuration, sets up logging and internationalization, creates an approval registry, initializes the Telegram service, and starts an HTTP server to handle approval requests. Dependencies include internal packages for configuration, logging, i18n, Telegram, HTTP API, and approvals.

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/codex-k8s/telegram-approver/internal/approvals"
    "github.com/codex-k8s/telegram-approver/internal/config"
    httpapi "github.com/codex-k8s/telegram-approver/internal/http"
    "github.com/codex-k8s/telegram-approver/internal/i18n"
    "github.com/codex-k8s/telegram-approver/internal/log"
    "github.com/codex-k8s/telegram-approver/internal/telegram"
)

func main() {
    // Load configuration from environment variables
    cfg, err := config.Load()
    if err != nil {
        panic(err)
    }

    // Initialize logger and i18n bundle
    logger := log.New(cfg.LogLevel)
    bundle, _ := i18n.Load(cfg.Lang)

    // Create approval registry (handles one request at a time)
    registry := approvals.NewRegistry()

    // Initialize Telegram service
    service, _ := telegram.New(cfg, bundle, registry, logger)

    // Create HTTP server with approval handler
    server := httpapi.New(cfg.HTTPAddr, logger)
    server.Handle("/approve", httpapi.NewApproveHandler(service, cfg, logger))

    // Start Telegram updates processing
    ctx := context.Background()
    service.Start(ctx)
    server.SetReady(true)

    // Run HTTP server
    server.ListenAndServe()
}
```

--------------------------------

### GET /readyz

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Readiness probe endpoint for Kubernetes. Returns 200 OK when the service is ready to accept approval requests, 503 Service Unavailable otherwise.

```APIDOC
## GET /readyz

### Description
Readiness probe endpoint for Kubernetes. Returns 200 OK when the service is ready to accept approval requests, 503 Service Unavailable otherwise.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- **Body**: `ok` (string)

#### Error Response (503)
- **Body**: `not ready` (string)

### Response Example
```
ok
```
```

--------------------------------

### Directly Use Approval Registry for Requests (Go)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

This Go code illustrates direct interaction with the `approvals.Registry`. It shows how to acquire exclusive access, start a new approval request with specific details, simulate an external resolution, and wait for the decision with a timeout. The registry ensures that only one request is processed at a time, and it handles the lifecycle of an approval request from start to resolution.

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/codex-k8s/telegram-approver/internal/approvals"
)

func main() {
    registry := approvals.NewRegistry()

    // Acquire exclusive access (blocks if another request is active)
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    if err := registry.Acquire(ctx); err != nil {
        fmt.Println("Failed to acquire:", err)
        return
    }
    defer registry.Release()

    // Start a new approval request
    approval, err := registry.Start(approvals.Request{
        CorrelationID: "req-456",
        Tool:          "delete_database",
        Arguments:     map[string]any{"database": "production"},
    })
    if err != nil {
        fmt.Println("Failed to start:", err)
        return
    }
    defer registry.Clear(approval)

    // Simulate external resolution (normally done by Telegram handler)
    go func() {
        time.Sleep(2 * time.Second)
        registry.Resolve(approval, approvals.DecisionApprove, "approved by admin")
    }()

    // Wait for result with timeout
    result := registry.Wait(ctx, approval, 1*time.Minute, "timeout")
    fmt.Printf("Decision: %s, Reason: %s\n", result.Decision, result.Reason)
    // Output: Decision: approve, Reason: approved by admin
}
```

--------------------------------

### Install ffmpeg for Voice Transcription

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Installs the ffmpeg package on Debian-based systems (like Ubuntu) which is required for voice message transcription by the telegram-approver service when using OpenAI STT.

```bash
sudo apt-get install -y ffmpeg
```

--------------------------------

### GET /healthz, GET /readyz

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Kubernetes health check endpoints.

```APIDOC
## GET /healthz, GET /readyz

### Description
These endpoints are used for Kubernetes health checks. `/healthz` typically checks if the service is running, while `/readyz` checks if the service is ready to accept traffic.

### Method
GET

### Endpoint
/healthz
/readyz

### Response
#### Success Response (200)
(Typically an empty 200 OK response indicating the health status.)
```

--------------------------------

### Telegram Approver API Response Example

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Example JSON response from the POST /approve API endpoint. It indicates the user's decision and any accompanying reason.

```json
{
  "decision": "approve",
  "reason": "approved"
}
```

--------------------------------

### Telegram Approver API Request Example

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Example JSON payload for the POST /approve API endpoint. It includes a correlation ID, the tool initiating the request, arguments for the operation, and a timeout in seconds.

```json
{
  "correlation_id": "req-123",
  "tool": "github_create_env_secret_k8s",
  "arguments": {
    "namespace": "ai-staging",
    "k8s_secret_name": "pg-password"
  },
  "timeout_sec": 3600
}
```

--------------------------------

### Docker Compose for Telegram Approver Integration (YAML)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

This YAML configuration defines a Docker Compose setup for integrating the `telegram-approver` service with `yaml-mcp-server`. It specifies the Docker images, environment variables required for each service (including Telegram bot tokens and chat IDs), port mappings, and health checks for the `telegram-approver`. The `yaml-mcp-server` is configured to use the `telegram-approver`'s URL and depends on its healthy status.

```yaml
version: '3.8'
services:
  telegram-approver:
    image: ghcr.io/codex-k8s/telegram-approver:latest
    environment:
      TG_APPROVER_TOKEN: ${TELEGRAM_BOT_TOKEN}
      TG_APPROVER_CHAT_ID: ${TELEGRAM_CHAT_ID}
      TG_APPROVER_HTTP_ADDR: ":8080"
      TG_APPROVER_APPROVAL_TIMEOUT: "1h"
      TG_APPROVER_LOG_LEVEL: "info"
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
      interval: 10s
      timeout: 5s
      retries: 3

  yaml-mcp-server:
    image: ghcr.io/codex-k8s/yaml-mcp-server:latest
    environment:
      APPROVER_URL: "http://telegram-approver:8080"
    depends_on:
      telegram-approver:
        condition: service_healthy
```

--------------------------------

### GET /healthz

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Liveness probe endpoint for Kubernetes health checks. Always returns 200 OK when the service is running.

```APIDOC
## GET /healthz

### Description
Liveness probe endpoint for Kubernetes health checks. Always returns 200 OK when the service is running.

### Method
GET

### Endpoint
/healthz

### Response
#### Success Response (200)
- **Body**: `ok` (string)

### Response Example
```
ok
```
```

--------------------------------

### Kubernetes Health Check Endpoints (Bash)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Provides liveness and readiness probes for Kubernetes. '/healthz' checks if the service is running, while '/readyz' checks if it's ready to accept requests. Both return HTTP 200 on success.

```bash
curl http://localhost:8080/healthz
# Response: ok (HTTP 200)
```

```bash
curl http://localhost:8080/readyz
# Response when ready: ok (HTTP 200)
# Response when not ready: not ready (HTTP 503)
```

--------------------------------

### Telegram Approver Configuration (Bash)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Sets environment variables to configure the telegram-approver service. Required variables include the Telegram bot token and chat ID. Optional variables control the listen address, language, timeouts, log level, and webhook/voice transcription settings.

```bash
# Required: Telegram bot token from @BotFather
export TG_APPROVER_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

# Required: Telegram chat ID (user who can approve/deny)
export TG_APPROVER_CHAT_ID="987654321"

# Optional: HTTP listen address (default: :8080)
export TG_APPROVER_HTTP_ADDR=":8080"

# Optional: Language for messages (en or ru, default: en)
export TG_APPROVER_LANG="en"

# Optional: Maximum wait time for approval (default: 1h)
export TG_APPROVER_APPROVAL_TIMEOUT="1h"

# Optional: Custom timeout message appended to Telegram message
export TG_APPROVER_TIMEOUT_MESSAGE="Request expired. Please submit again."

# Optional: Log level (debug, info, warn, error, default: info)
export TG_APPROVER_LOG_LEVEL="info"

# Optional: Graceful shutdown timeout (default: 10s)
export TG_APPROVER_SHUTDOWN_TIMEOUT="10s"

# Webhook mode (both must be set together)
export TG_APPROVER_WEBHOOK_URL="https://your-domain.com/webhook"
export TG_APPROVER_WEBHOOK_SECRET="your-secret-token"

# Voice transcription (optional, requires ffmpeg)
export TG_APPROVER_OPENAI_API_KEY="sk-..."
export TG_APPROVER_STT_MODEL="gpt-4o-mini-transcribe"
export TG_APPROVER_STT_TIMEOUT="30s"
```

--------------------------------

### Development Script

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Executes a local development script named 'update.sh' located in the 'dev' directory. This script is likely used for tasks related to development, testing, or building the project.

```bash
./dev/update.sh
```

--------------------------------

### POST /approve

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Receives approval requests from yaml-mcp-server, sends them to Telegram, and waits for a user decision.

```APIDOC
## POST /approve

### Description
This endpoint receives an approval request, forwards it to a Telegram user for a decision (Approve, Deny, or Deny with message), and returns the user's decision.

### Method
POST

### Endpoint
/approve

### Parameters
#### Request Body
- **correlation_id** (string) - Required - Unique identifier for the request.
- **tool** (string) - Required - The name of the tool or operation being approved.
- **arguments** (object) - Required - Key-value pairs representing the arguments for the operation.
  - **namespace** (string) - Required - The Kubernetes namespace.
  - **k8s_secret_name** (string) - Required - The name of the Kubernetes secret.
- **timeout_sec** (integer) - Required - The timeout in seconds for the approval request.

### Request Example
```json
{
  "correlation_id": "req-123",
  "tool": "github_create_env_secret_k8s",
  "arguments": {
    "namespace": "ai-staging",
    "k8s_secret_name": "pg-password"
  },
  "timeout_sec": 3600
}
```

### Response
#### Success Response (200)
- **decision** (string) - The user's decision ('approve', 'deny', or 'error' on timeout).
- **reason** (string) - The reason for the decision, if provided (e.g., 'approved', 'denied', or a denial message).

#### Response Example
```json
{
  "decision": "approve",
  "reason": "approved"
}
```
```

--------------------------------

### POST /webhook

Source: https://github.com/codex-k8s/telegram-approver/blob/main/README_EN.md

Telegram webhook endpoint for receiving updates from Telegram.

```APIDOC
## POST /webhook

### Description
This endpoint serves as the Telegram webhook, receiving updates directly from the Telegram Bot API. It is used for receiving user interactions with the bot, such as approvals or denials.

### Method
POST

### Endpoint
/webhook

### Parameters
#### Headers
- **X-Telegram-Bot-Api-Secret-Token** (string) - Required - The secret token configured for the webhook to verify the request origin.

### Request Body
(Telegram Bot API Update object)

### Response
(Typically an empty 200 OK response to acknowledge receipt of the update)
```

--------------------------------

### POST /approve

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Submit an approval request that will be sent to Telegram and block until a decision is made or timeout occurs.

```APIDOC
## POST /approve

### Description
Submit an approval request that will be sent to Telegram and block until a decision is made or timeout occurs.

### Method
POST

### Endpoint
/approve

### Parameters
#### Request Body
- **correlation_id** (string) - Required - Unique identifier for the request.
- **tool** (string) - Required - The tool or service making the request.
- **arguments** (object) - Required - Key-value pairs of arguments for the operation.
  - **namespace** (string) - Required - Kubernetes namespace.
  - **k8s_secret_name** (string) - Required - Kubernetes secret name.
- **timeout_sec** (integer) - Optional - Timeout in seconds for the approval (default: 3600).

### Request Example
```json
{
  "correlation_id": "req-123",
  "tool": "github_create_env_secret_k8s",
  "arguments": {
    "namespace": "ai-staging",
    "k8s_secret_name": "pg-password"
  },
  "timeout_sec": 3600
}
```

### Response
#### Success Response (200)
- **decision** (string) - The decision made (approve, deny, error).
- **reason** (string) - The reason for the decision.

#### Response Example
```json
{
  "decision": "approve",
  "reason": "approved"
}
```

#### Error Response (e.g., Timeout)
```json
{
  "decision": "error",
  "reason": "approval timeout"
}
```
```

--------------------------------

### Handle Approval Decisions (Go)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

This Go code snippet defines a function `handleResult` that processes the outcome of an approval request. It uses a switch statement to differentiate between `DecisionApprove`, `DecisionDeny`, and `DecisionError`, executing specific logic based on the decision and its associated reason. This pattern is crucial for determining the next steps after a user interacts with the approval request.

```go
package main

import (
    "fmt"

    "github.com/codex-k8s/telegram-approver/internal/approvals"
)

func handleResult(result approvals.Result) {
    switch result.Decision {
    case approvals.DecisionApprove:
        fmt.Println("Request approved:", result.Reason)
        // Proceed with the risky operation

    case approvals.DecisionDeny:
        fmt.Println("Request denied:", result.Reason)
        // Abort the operation, log the denial reason

    case approvals.DecisionError:
        fmt.Println("Request failed:", result.Reason)
        // Handle timeout or system error
    }
}

// Example decisions:
// - DecisionApprove with Reason: "approved"
// - DecisionDeny with Reason: "denied" or custom message
// - DecisionError with Reason: "approval timeout" or "request cancelled"
```

--------------------------------

### Submit Approval Request (Bash)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Submits an approval request to the /approve endpoint. It blocks until a decision is made or a timeout occurs. The request includes a correlation ID, tool name, arguments, and timeout. Responses indicate 'approve', 'deny', 'error', or 'timeout'.

```bash
curl -X POST http://localhost:8080/approve \
  -H "Content-Type: application/json" \
  -d '{
    "correlation_id": "req-123",
    "tool": "github_create_env_secret_k8s",
    "arguments": {
      "namespace": "ai-staging",
      "k8s_secret_name": "pg-password"
    },
    "timeout_sec": 3600
  }'
```

--------------------------------

### Telegram Webhook Configuration (Bash)

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Configures the Telegram webhook endpoint for receiving updates. This mode is active when TG_APPROVER_WEBHOOK_URL and TG_APPROVER_WEBHOOK_SECRET are set. The secret token is passed via the X-Telegram-Bot-Api-Secret-Token header.

```bash
# Configure via environment variables:
export TG_APPROVER_WEBHOOK_URL="https://your-domain.com/webhook"
export TG_APPROVER_WEBHOOK_SECRET="your-secret-token"
```

--------------------------------

### POST /webhook

Source: https://context7.com/codex-k8s/telegram-approver/llms.txt

Telegram webhook endpoint. Receives updates from Telegram when users interact with approval messages. The secret is verified via the `X-Telegram-Bot-Api-Secret-Token` header.

```APIDOC
## POST /webhook

### Description
Telegram webhook endpoint (only available when webhook mode is configured). Receives updates from Telegram when users interact with approval messages. The secret is verified via the `X-Telegram-Bot-Api-Secret-Token` header.

### Method
POST

### Endpoint
/webhook

### Headers
- **X-Telegram-Bot-Api-Secret-Token** (string) - Required - The secret token for webhook verification.

### Notes
This endpoint is called by Telegram, not manually. It requires `TG_APPROVER_WEBHOOK_URL` and `TG_APPROVER_WEBHOOK_SECRET` environment variables to be set.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.