> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt > Use this file to discover all available pages before exploring further. # Crear un message template > Crea un nuevo message template en Kapso usando variables nombradas (`parameter_format: NAMED`). Las variables se declaran por nombre en el body, ej. `{{nombre}}`, y no requieren orden. Si el workspace no tiene credenciales Kapso devuelve 409. ## OpenAPI ````yaml /openapi/public-api.yaml post /v1/message-templates openapi: 3.1.0 info: title: Agents Studio API version: 1.0.0 description: > API del backend de Agents Studio. Expone servicios multi-tenant para gestionar agentes (texto y voz), catálogo de herramientas, habilitación de workspaces y operaciones de telefonía. Todos los endpoints requieren autenticación Bearer y respetan los contratos documentados en `docs/modules`. license: name: Proprietary url: https://getsupervisor.ai/legal/terms servers: - url: https://api-prod.studio.getsupervisor.ai description: Producción - url: https://sandbox.agents.studio.getsupervisor.ai description: Sandbox security: - BearerAuth: [] tags: - name: Agents description: > Gestión general de agentes y sus metadatos. Scopes requeridos: `agents:read` para consultas y `agents:write` para creación, actualización y operaciones sobre teléfonos. - name: Agent Versions description: Versionado y mantenimiento de versiones publicadas de los agentes. - name: Agent Schedules description: >- Configuración de horarios regulares y excepciones puntuales para controlar la disponibilidad de los agentes. - name: Campaigns description: > Gestión de campañas masivas basadas en CSV para ejecutar agentes de forma batch. Scopes requeridos: `campaigns:read` para consultas y `campaigns:write` para creación. - name: Calls description: | Consultas de llamadas (Speech Analytics) disponibles para el workspace. Scopes requeridos: `calls:read`. - name: Agent Instructions description: > Operaciones sobre instrucciones (prompt) gestionadas por los usuarios finales para guiar y corregir el comportamiento del agente. Las instrucciones se aplican a la versión activa del agente, se mantienen como texto libre sin formato (1 a 500 caracteres) y su prioridad se controla mediante el campo `order`. Scopes requeridos: `agent-instructions:read` para consultas y `agent-instructions:write` para creación o edición. - name: Catalogs description: > Gestión centralizada de catálogos (idiomas, estilos de mensaje, tonos, etiquetas, voces y eventos de webhook) con alcance global o específico por workspace. Las voces del workspace se consultan aquí, con `GET /v1/catalogs/items?type=voice`. Scopes requeridos: `catalogs:read` para consultas y `catalogs:write` para creación y modificaciones. - name: Catalog Templates description: > Catálogo de plantillas de agente publicadas. Sirve para descubrir qué plantillas hay disponibles y con qué `agentVersionId` clonarlas mediante `POST /v1/agents/from-template`. Scopes requeridos: `catalogs:read`. - name: Agent Phones description: Conexión y desconexión de teléfonos asignados a agentes. - name: API Keys description: Gestión de credenciales de acceso programático y sus permisos. - name: Agent Blueprints description: > Gestión del blueprint (personalidad) asociado a cada versión de agente. Scopes requeridos: `agent-blueprints:read` para lectura y `agent-blueprints:write` para cambios en blueprint. - name: Blueprint Stages description: > Autoría de stages de un blueprint del agente, abarcando orden, prompts y validaciones previas a la publicación. Todas las rutas cuelgan del blueprint (`/v1/agents/{agentId}/blueprints/{blueprintId}/stages`), así que hay que resolver primero el `blueprintId` con `GET /v1/agents/{agentId}/blueprints`. Scopes requeridos: `blueprint-stages:read` para consultas y `blueprint-stages:write` para creación y edición. La validación del grafo se ejecuta automáticamente en cada mutación y la sincronización con el proveedor sucede mediante jobs internos tras los cambios. - name: Stage Triggers description: > Gestión detallada de triggers que conectan stages dentro del blueprint y definen las transiciones conversacionales. Scopes requeridos: `stage-triggers:read` y `stage-triggers:write`. - name: Workspaces description: Gestión multi-tenant y habilitación de credenciales por workspace. - name: Tools description: > Catálogo y ejecución de tools disponibles para los agentes. Scopes requeridos: `tools:read` para listar y `tools:execute` para ejecutar tools. - name: Webhooks description: > Gestión de webhooks por workspace para suscribirse a eventos del dominio y recibir notificaciones HTTP. Scopes requeridos: `webhooks:read` para consultas y `webhooks:write` para crear, actualizar o eliminar webhooks y suscripciones. - name: SIP Trunks description: > Provisionamiento y gestión de SIP trunks para conectar agentes de voz con carriers PSTN (Twilio, ccc2.uno, etc.) via Kamailio. Genera credenciales digest automaticamente. Scopes requeridos: `sip:read` para consultas y `sip:write` para creación, actualización y eliminación. - name: Documents description: > Gestión de documentos asociados al workspace. Permite obtener URLs presignadas para subir archivos que luego se referencian al crear o personalizar agentes. Scopes requeridos: `documents:write`. - name: Message Templates description: > Gestión de message templates de WhatsApp (Kapso). Permite crear, listar y eliminar templates, así como consultar el estado de la conexión con el número de teléfono configurado. Scopes requeridos: `agents:read` para consultas y `agents:write` para creación y eliminación. - name: Billing description: | Consulta del balance de consumo del workspace sobre el plan contratado. Scopes requeridos: `billing:read`. - name: Usage description: | Consultas de consumo de recursos agregado por agente. Scopes requeridos: `usage:read`. - name: Health description: > Sonda de disponibilidad del servicio. No requiere autenticación ni `X-Workspace-Id`. paths: /v1/message-templates: post: tags: - Message Templates summary: Crear un message template description: > Crea un nuevo message template en Kapso usando variables nombradas (`parameter_format: NAMED`). Las variables se declaran por nombre en el body, ej. `{{nombre}}`, y no requieren orden. Si el workspace no tiene credenciales Kapso devuelve 409. operationId: createMessageTemplate parameters: - $ref: '#/components/parameters/XWorkspaceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMessageTemplateRequest' examples: basic: summary: Template de texto con variables nombradas value: channel: whatsapp name: promo_verano body: >- Hola {{nombre}}, tu descuento del {{porcentaje}}% ya está activo. metadata: category: marketing language: es_MX footer: Responde STOP para no recibir más mensajes. responses: '201': description: Template creado en Kapso content: application/json: schema: $ref: '#/components/schemas/MessageTemplateResponse' examples: created: summary: Template creado exitosamente value: id: abc123 channel: whatsapp name: promo_verano category: marketing status: pending language: es_MX body: >- Hola {{nombre}}, tu descuento del {{porcentaje}}% ya está activo. '400': description: Payload inválido (nombre, cuerpo o variables mal formateados) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: WHATSAPP_TEMPLATE_INVALID_NAME message: Template name is invalid after normalization '409': description: Credenciales Kapso no configuradas para el workspace content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: WHATSAPP_CREDENTIALS_NOT_CONFIGURED message: WhatsApp credentials not configured for this workspace components: parameters: XWorkspaceId: name: x-workspace-id in: header required: true description: Identificador del workspace multi-tenant. schema: type: string format: uuid schemas: CreateMessageTemplateRequest: type: object description: Payload para crear un nuevo message template en Kapso. properties: channel: type: string enum: - whatsapp description: Canal de mensajería. Actualmente solo `whatsapp`. name: type: string minLength: 1 maxLength: 512 description: >- Nombre del template. Se normaliza a snake_case antes de enviarse a Kapso. body: type: string minLength: 1 maxLength: 1024 description: >- Cuerpo del mensaje. Las variables se nombran en snake_case minúscula, ej. `{{nombre}}`; no requieren orden. metadata: $ref: '#/components/schemas/WhatsAppMetadataRequest' required: - channel - name - body MessageTemplateResponse: type: object description: Representación de un message template registrado en Kapso. properties: id: type: string description: Identificador del template en Kapso. channel: type: string enum: - whatsapp description: Canal de mensajería del template. name: type: string description: >- Nombre normalizado del template (snake_case, solo letras, números y guiones bajos). category: type: string enum: - utility - marketing - authentication description: >- Categoría del template según la clasificación de WhatsApp Business API. status: type: string description: >- Estado de aprobación del template (ej. `approved`, `pending`, `rejected`). language: type: string description: Código de idioma del template (ej. `es_MX`, `es_ES`). body: type: string description: >- Texto del cuerpo del template. Las variables se representan con nombre, ej. `{{nombre}}`. required: - id - channel - name - category - status - language - body ErrorResponse: type: object properties: code: type: string description: Código principal del error (alto nivel). message: type: string description: Mensaje legible para humanos. details: type: object description: > Información adicional específica del error. Cuando aplique, `details.subcode` provee un identificador estable para que el frontend decida qué UI mostrar. properties: subcode: type: string description: >- Identificador específico del error (p.ej. `WORKSPACE_NOT_PROVISIONED`). workspaceId: type: string format: uuid description: Identificador de workspace relacionado cuando aplica. additionalProperties: true required: - code - message WhatsAppMetadataRequest: type: object description: Metadatos específicos de WhatsApp para la creación del template. properties: category: type: string enum: - utility - marketing - authentication description: Categoría del template. Por defecto `utility`. language: type: string enum: - es_MX - es_ES description: Código de idioma. Por defecto `es_MX`. header: type: string maxLength: 60 description: Texto del encabezado del template (opcional). footer: type: string maxLength: 60 description: Texto del pie de página del template (opcional). buttons: type: array items: $ref: '#/components/schemas/WhatsAppButtonRequest' description: Botones de acción asociados al template (opcional). WhatsAppButtonRequest: type: object description: Botón de acción rápida o CTA para incluir en el template de WhatsApp. properties: type: type: string enum: - quick_reply - url - phone - phone_number description: Tipo de botón. text: type: string minLength: 1 maxLength: 200 description: Texto visible del botón. value: type: string maxLength: 2000 description: >- URL o número de teléfono asociado (requerido para `url` y `phone`/`phone_number`). required: - type - text securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````