@1claw/openapi-spec 0.42.0 → 0.43.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "2.28.0",
+    "version": "2.29.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations, cloud runtimes,\nagent memory, and discovery.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.xyz"
@@ -150,6 +150,14 @@
     {
       "name": "Discovery",
       "description": "Agent directory and platform marketplace"
+    },
+    {
+      "name": "Agent Chat",
+      "description": "Chat with agents via Shroud LLM proxy"
+    },
+    {
+      "name": "Agent Channels",
+      "description": "External messaging channels (Telegram, WhatsApp, Discord)"
     }
   ],
   "paths": {
@@ -11444,177 +11452,748 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      },
-      "ApiKeyAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "1ck_ prefixed API key used as Bearer token"
-      }
     },
-    "parameters": {
-      "VaultId": {
-        "name": "vault_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "SecretPath": {
-        "name": "path",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string"
+    "/v1/agents/{agent_id}/chat": {
+      "post": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "Send chat message",
+        "description": "Send a message to an agent and receive a response via Shroud LLM.\nSupports SSE streaming when Accept: text/event-stream is set.\n",
+        "operationId": "sendChatMessage",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SendChatMessageRequest"
+              }
+            }
+          }
         },
-        "description": "Secret path (e.g. \"db/credentials\")"
-      },
-      "AgentId": {
-        "name": "agent_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "PolicyId": {
-        "name": "policy_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "CardId": {
-        "name": "card_id",
-        "in": "path",
-        "required": true,
-        "schema": {
-          "type": "string",
-          "format": "uuid"
-        }
-      },
-      "IncludeSignedTx": {
-        "name": "include_signed_tx",
-        "in": "query",
-        "required": false,
-        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
-        "schema": {
-          "type": "boolean",
-          "default": false,
-          "example": false
+        "responses": {
+          "200": {
+            "description": "Chat response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SendChatMessageResponse"
+                }
+              },
+              "text/event-stream": {
+                "schema": {
+                  "type": "string",
+                  "description": "SSE stream of response chunks"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
         }
       }
     },
-    "responses": {
-      "BadRequest": {
-        "description": "Invalid request",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
-            }
+    "/v1/agents/{agent_id}/chat/conversations": {
+      "get": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "List conversations",
+        "description": "List all chat conversations for an agent.",
+        "operationId": "listChatConversations",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
           }
-        }
-      },
-      "Unauthorized": {
-        "description": "Authentication required or invalid",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+        ],
+        "responses": {
+          "200": {
+            "description": "Conversation list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChatConversationListResponse"
+                }
+              }
             }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
           }
         }
-      },
-      "Forbidden": {
-        "description": "Insufficient permissions",
-        "content": {
-          "application/json": {
+      }
+    },
+    "/v1/agents/{agent_id}/chat/conversations/{conversation_id}": {
+      "get": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "Get conversation",
+        "description": "Get a conversation with its full message history.",
+        "operationId": "getChatConversation",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+              "type": "string",
+              "format": "uuid"
             }
           }
-        }
-      },
-      "NotFound": {
-        "description": "Resource not found",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
+        ],
+        "responses": {
+          "200": {
+            "description": "Conversation detail",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConversationDetailResponse"
+                }
+              }
             }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       },
-      "PaymentRequired": {
-        "description": "x402 payment required",
-        "content": {
-          "application/json": {
+      "delete": {
+        "tags": [
+          "Agent Chat"
+        ],
+        "summary": "Archive conversation",
+        "description": "Archive (soft-delete) a chat conversation.",
+        "operationId": "deleteChatConversation",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "$ref": "#/components/schemas/PaymentRequirement"
+              "type": "string",
+              "format": "uuid"
             }
           }
-        }
-      },
-      "Conflict": {
-        "description": "Resource already exists or conflict",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ProblemDetails"
-            }
+        ],
+        "responses": {
+          "204": {
+            "description": "Conversation archived"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       }
     },
-    "schemas": {
-      "OrderCardRequest": {
-        "type": "object",
-        "required": [
-          "kind",
-          "amount_usd"
+    "/v1/agents/{agent_id}/channels": {
+      "post": {
+        "tags": [
+          "Agent Channels"
         ],
-        "properties": {
-          "kind": {
-            "type": "string",
-            "enum": [
-              "prepaid",
-              "gift_card"
-            ]
-          },
-          "amount_usd": {
-            "type": "string",
-            "description": "USD amount to load onto the card.",
-            "example": "25.00"
-          },
-          "laso_server_id": {
-            "type": "string",
-            "description": "Optional Laso gift-card server/brand id (gift cards only)."
-          },
-          "country": {
-            "type": "string",
-            "description": "Optional country (prepaid cards; defaults to US)."
+        "summary": "Register channel",
+        "description": "Register a new external messaging channel (Telegram, WhatsApp, Discord)\nfor an agent. Human-only. Returns the channel with its webhook URL.\n",
+        "operationId": "createChannel",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
           }
-        }
-      },
-      "CardResponse": {
-        "type": "object",
-        "description": "Masked card view — never contains PAN/CVV.",
-        "required": [
-          "id",
-          "issuer",
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateChannelRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Channel created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "List channels",
+        "description": "List all messaging channels for an agent.",
+        "operationId": "listChannels",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Channel list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels/{channel_id}": {
+      "patch": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Update channel",
+        "description": "Update a channel's name, active status, or config. Human-only.",
+        "operationId": "updateChannel",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateChannelRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Channel updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Delete channel",
+        "description": "Delete a messaging channel. Human-only.",
+        "operationId": "deleteChannel",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Channel deleted"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels/{channel_id}/send": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Send outbound message",
+        "description": "Send an outbound message via a registered channel.",
+        "operationId": "sendChannelMessage",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SendChannelMessageRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Message sent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelMessageResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/channels/{channel_id}/messages": {
+      "get": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Channel message history",
+        "description": "List inbound and outbound messages for a channel.",
+        "operationId": "listChannelMessages",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "channel_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 50
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Message list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ChannelMessageListResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/telegram/{webhook_path}": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Telegram webhook",
+        "description": "Public webhook endpoint for receiving Telegram bot updates.",
+        "operationId": "telegramWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/whatsapp/{webhook_path}": {
+      "get": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "WhatsApp webhook verification",
+        "description": "Verification endpoint for WhatsApp Cloud API webhook setup.",
+        "operationId": "whatsappWebhookVerify",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "hub.mode",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "hub.verify_token",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "hub.challenge",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Challenge response"
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "WhatsApp webhook",
+        "description": "Public webhook endpoint for receiving WhatsApp Cloud API events.",
+        "operationId": "whatsappWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/discord/{webhook_path}": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Discord webhook",
+        "description": "Public webhook endpoint for receiving Discord bot interactions.",
+        "operationId": "discordWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      },
+      "ApiKeyAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "1ck_ prefixed API key used as Bearer token"
+      }
+    },
+    "parameters": {
+      "VaultId": {
+        "name": "vault_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "SecretPath": {
+        "name": "path",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string"
+        },
+        "description": "Secret path (e.g. \"db/credentials\")"
+      },
+      "AgentId": {
+        "name": "agent_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "PolicyId": {
+        "name": "policy_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "CardId": {
+        "name": "card_id",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "IncludeSignedTx": {
+        "name": "include_signed_tx",
+        "in": "query",
+        "required": false,
+        "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n",
+        "schema": {
+          "type": "boolean",
+          "default": false,
+          "example": false
+        }
+      }
+    },
+    "responses": {
+      "BadRequest": {
+        "description": "Invalid request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Authentication required or invalid",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "Insufficient permissions",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "Resource not found",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      },
+      "PaymentRequired": {
+        "description": "x402 payment required",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/PaymentRequirement"
+            }
+          }
+        }
+      },
+      "Conflict": {
+        "description": "Resource already exists or conflict",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ProblemDetails"
+            }
+          }
+        }
+      }
+    },
+    "schemas": {
+      "OrderCardRequest": {
+        "type": "object",
+        "required": [
+          "kind",
+          "amount_usd"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "prepaid",
+              "gift_card"
+            ]
+          },
+          "amount_usd": {
+            "type": "string",
+            "description": "USD amount to load onto the card.",
+            "example": "25.00"
+          },
+          "laso_server_id": {
+            "type": "string",
+            "description": "Optional Laso gift-card server/brand id (gift cards only)."
+          },
+          "country": {
+            "type": "string",
+            "description": "Optional country (prepaid cards; defaults to US)."
+          }
+        }
+      },
+      "CardResponse": {
+        "type": "object",
+        "description": "Masked card view — never contains PAN/CVV.",
+        "required": [
+          "id",
+          "issuer",
           "kind",
           "currency",
           "status",
@@ -20089,6 +20668,307 @@
             }
           }
         }
+      },
+      "SendChatMessageRequest": {
+        "type": "object",
+        "required": [
+          "message"
+        ],
+        "properties": {
+          "message": {
+            "type": "string"
+          },
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "mode": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "system_prompt": {
+            "type": "string"
+          }
+        }
+      },
+      "ChatMessageResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "role": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "tool_calls": {},
+          "tool_results": {},
+          "tokens_prompt": {
+            "type": "integer"
+          },
+          "tokens_completion": {
+            "type": "integer"
+          },
+          "model": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChatConversationResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "title": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChatConversationListResponse": {
+        "type": "object",
+        "properties": {
+          "conversations": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChatConversationResponse"
+            }
+          }
+        }
+      },
+      "ConversationDetailResponse": {
+        "type": "object",
+        "properties": {
+          "conversation": {
+            "$ref": "#/components/schemas/ChatConversationResponse"
+          },
+          "messages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChatMessageResponse"
+            }
+          }
+        }
+      },
+      "SendChatMessageResponse": {
+        "type": "object",
+        "properties": {
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "message": {
+            "$ref": "#/components/schemas/ChatMessageResponse"
+          }
+        }
+      },
+      "CreateChannelRequest": {
+        "type": "object",
+        "required": [
+          "channel_type",
+          "config"
+        ],
+        "properties": {
+          "channel_type": {
+            "type": "string",
+            "enum": [
+              "telegram",
+              "whatsapp",
+              "discord"
+            ]
+          },
+          "channel_name": {
+            "type": "string"
+          },
+          "config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Platform-specific config.\nTelegram: { bot_token }.\nWhatsApp: { phone_number_id, access_token, verify_token }.\nDiscord: { bot_token, application_id }.\n"
+          }
+        }
+      },
+      "UpdateChannelRequest": {
+        "type": "object",
+        "properties": {
+          "channel_name": {
+            "type": "string"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "config": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ChannelResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "channel_type": {
+            "type": "string",
+            "enum": [
+              "telegram",
+              "whatsapp",
+              "discord"
+            ]
+          },
+          "channel_name": {
+            "type": "string"
+          },
+          "webhook_path": {
+            "type": "string"
+          },
+          "webhook_url": {
+            "type": "string"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChannelListResponse": {
+        "type": "object",
+        "properties": {
+          "channels": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChannelResponse"
+            }
+          }
+        }
+      },
+      "SendChannelMessageRequest": {
+        "type": "object",
+        "required": [
+          "external_chat_id",
+          "content"
+        ],
+        "properties": {
+          "external_chat_id": {
+            "type": "string",
+            "description": "External platform chat/user ID"
+          },
+          "content": {
+            "type": "string"
+          },
+          "reply_to": {
+            "type": "string",
+            "description": "External message ID to reply to"
+          }
+        }
+      },
+      "ChannelMessageResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "channel_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound"
+            ]
+          },
+          "external_chat_id": {
+            "type": "string"
+          },
+          "external_message_id": {
+            "type": "string"
+          },
+          "sender_name": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "media_url": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ChannelMessageListResponse": {
+        "type": "object",
+        "properties": {
+          "messages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChannelMessageResponse"
+            }
+          }
+        }
       }
     }
   }