{ "openapi": "3.1.0", "info": { "title": "ZapZap API", "description": "API REST para conectar números de WhatsApp por QR y enviar, recibir y automatizar mensajes. Autentica con los encabezados `x-api-key` y `x-api-secret` (Configuración y API en el panel). El canal usa QR y no es la API oficial de Meta: WhatsApp puede restringir números que envían mensajes no deseados. Documentación: https://zapzapapi.com/es/docs", "version": "1.0.0", "contact": { "name": "ZapZap API", "url": "https://zapzapapi.com" } }, "servers": [ { "url": "https://api.zapzapapi.com/api/v1" } ], "tags": [ { "name": "Cuenta e Instancias" }, { "name": "Enviar Mensajes" }, { "name": "Conversaciones" }, { "name": "Contactos y Perfil" }, { "name": "Grupos" }, { "name": "Newsletters y Canales" }, { "name": "Campañas" }, { "name": "Llamadas" }, { "name": "WhatsApp Business" }, { "name": "Configuración" }, { "name": "Webhooks y Eventos" }, { "name": "Cola Async" }, { "name": "Chatbot e IA" }, { "name": "CRM y Leads" }, { "name": "Integración con Chatwoot" }, { "name": "Flujos" }, { "name": "Seguimiento de Meta" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" }, "ApiSecret": { "type": "apiKey", "in": "header", "name": "x-api-secret" } } }, "security": [ { "ApiKey": [], "ApiSecret": [] } ], "paths": { "/account": { "get": { "operationId": "management_account", "summary": "Datos de la Cuenta", "description": "Devuelve los datos de tu cuenta: nombre, email, saldo actual, día de cobro y estado.", "tags": [ "Cuenta e Instancias" ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "uuid", "name": "João", "email": "joao@email.com", "balance": "150.00", "billing_day": 10, "status": "ACTIVE" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances": { "get": { "operationId": "management_list_instances", "summary": "Listar Instancias", "description": "Lista todas las instancias de WhatsApp de tu cuenta con estado, nombre, teléfono y configuración.", "tags": [ "Cuenta e Instancias" ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "uuid", "name": "minha-instancia", "status": "CONNECTED", "phone_number": "5511999999999" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "post": { "operationId": "management_create_instance", "summary": "Crear Instancia", "description": "Crea una nueva instancia de WhatsApp. Debita automáticamente del saldo (tarifa de activación + proporcional). El nombre debe contener solo letras, números, _ y -.", "tags": [ "Cuenta e Instancias" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Nombre de la instancia", "type": "string", "example": "minha-instancia" }, "systemName": { "description": "Nombre del sistema (se muestra en WhatsApp)", "type": "string", "example": "Meu App" }, "metadata": { "description": "Datos libres (JSON): vincúlalos a tu sistema (ej: clientId, plan)", "type": "string", "example": "{\"clientId\":\"123\",\"plan\":\"pro\"}" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "instance": { "id": "uuid", "name": "minha-instancia", "status": "PENDING" }, "billing": { "charged": 10.5 } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances/cost": { "get": { "operationId": "management_creation_cost", "summary": "Costo de Creación", "description": "Devuelve el costo de crear una nueva instancia: tarifa de activación, proporcional y saldo necesario.", "tags": [ "Cuenta e Instancias" ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "activationFee": 3, "prorate": 7.5, "total": 10.5, "instancePrice": 15, "currentBalance": 150 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances/{id}": { "delete": { "operationId": "management_delete_instance", "summary": "Eliminar Instancia", "description": "Elimina (soft delete) una instancia. WhatsApp se desconecta y se genera una exención de la tarifa de activación para la próxima creación.", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Instância deletada com sucesso" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "get": { "operationId": "management_get_instance", "summary": "Detalles de la Instancia", "description": "Devuelve los detalles de una instancia específica.", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "uuid", "name": "MinhaInstancia", "status": "CONNECTED", "phone_number": "5511999999999" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "put": { "operationId": "management_update_instance", "summary": "Actualizar Instancia", "description": "Actualiza webhook_url y/o metadata de una instancia. El metadata es un JSON libre para vincular la instancia a tu sistema (ej: ID del cliente, plan, etc). El metadata se incluye automáticamente en los webhooks recibidos.", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "description": "URL del webhook (HTTPS)", "type": "string", "example": "https://meusite.com/webhook" }, "metadata": { "description": "Datos libres (JSON)", "type": "string", "example": "{\"clientId\":\"123\"}" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "uuid", "name": "minha-instancia", "webhook_url": "https://meusite.com/webhook", "metadata": { "clientId": "123" } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances/{id}/qrcode": { "get": { "operationId": "management_qrcode", "summary": "Código QR de la Instancia", "description": "Devuelve el código QR para conectar WhatsApp a la instancia. Escanéalo con el celular.", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "connected": true, "instance": { "status": "connected", "profileName": "Nome" } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances/{id}/webhook": { "get": { "operationId": "gestao_webhook_get", "summary": "Ver Webhook", "description": "Devuelve la URL de webhook configurada para la instancia. El webhook recibe eventos en tiempo real (mensajes, estado, etc).\n\n⚠️ ATENCIÓN A LA URL: el {id} ya va en la ruta: NO lo agregues dos veces.\n\n✅ Correcto: GET /api/v1/instances/TU-INSTANCE-ID/webhook\n❌ Incorrecto: GET /api/v1/TU-INSTANCE-ID/instances/TU-INSTANCE-ID/webhook (instanceId duplicado)", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "webhook_url": "https://meusite.com/webhook", "configured": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "put": { "operationId": "gestao_webhook_put", "summary": "Configurar Webhook", "description": "Define o actualiza la URL de webhook de la instancia. La URL debe ser pública y accesible por HTTPS. Eventos como mensajes recibidos, estado de entrega y cambios de conexión se enviarán por POST a esa URL.\n\n⚠️ ATENCIÓN A LA URL: el {id} ya va en la ruta: NO lo agregues dos veces.\n\n✅ Correcto: PUT /api/v1/instances/TU-INSTANCE-ID/webhook\n❌ Incorrecto: PUT /api/v1/TU-INSTANCE-ID/instances/TU-INSTANCE-ID/webhook (instanceId duplicado)", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "description": "URL del webhook (HTTPS)", "type": "string", "example": "https://meusite.com/webhook" }, "events": { "description": "Eventos a recibir (vacío = todos)", "type": "string", "example": "messages,status" }, "excludeMessages": { "description": "Excluir mensajes propios", "type": "boolean" } }, "required": [ "webhook_url" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "webhook_url": "https://meusite.com/webhook" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances/{id}/webhook/test": { "post": { "operationId": "gestao_webhook_test", "summary": "Probar Webhook", "description": "Envía un evento de prueba a la URL de webhook configurada. Devuelve el código de estado y el tiempo de respuesta. Útil para validar que tu servidor está recibiendo los eventos correctamente.\n\n⚠️ ATENCIÓN A LA URL: el {id} ya va en la ruta: NO lo agregues dos veces.\n\n✅ Correcto: POST /api/v1/instances/TU-INSTANCE-ID/webhook/test\n❌ Incorrecto: POST /api/v1/TU-INSTANCE-ID/instances/TU-INSTANCE-ID/webhook/test (instanceId duplicado)", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "URL alternativa para la prueba (opcional)", "type": "string", "example": "https://meusite.com/webhook" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "statusCode": 200, "responseTime": 150 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/wa_messages_limits": { "get": { "operationId": "instance_wa_limits", "summary": "Límites de Nuevas Conversaciones (WhatsApp)", "description": "Consulta el límite actual de nuevas conversaciones que WhatsApp permite iniciar desde este número (el 'tier' de la cuenta). Útil para seguir el calentamiento y evitar bloqueos por exceso de envíos.", "tags": [ "Cuenta e Instancias" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/carousel": { "post": { "operationId": "send_carousel", "summary": "Enviar Carrusel", "description": "Envía un carrusel de tarjetas con imagen y botones de acción. Cada elemento del array `carousel` representa una tarjeta con `text`, `image` y `buttons: [{type,text,id}]`.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "text": { "description": "Texto principal del mensaje", "type": "string", "example": "Confira nossas opções:" }, "carousel": { "description": "Tarjetas (array JSON)", "example": [ { "text": "Produto 1", "image": "https://exemplo.com/img.jpg", "buttons": [ { "type": "REPLY", "text": "Quero!", "id": "quero" } ] } ] }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "text", "carousel" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/contact": { "post": { "operationId": "send_contact", "summary": "Enviar Contacto (vCard)", "description": "Envía una tarjeta de contacto (vCard) con nombre y teléfono.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del destinatario", "type": "string", "example": "5511999999999" }, "fullName": { "description": "Nombre completo del contacto", "type": "string", "example": "João Silva" }, "phoneNumber": { "description": "Teléfonos (separados por coma)", "type": "string", "example": "5511999999999,5511888888888" }, "organization": { "description": "Empresa / Organización", "type": "string", "example": "Empresa XYZ" }, "email": { "description": "Email del contacto", "type": "string", "example": "joao@empresa.com" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "fullName", "phoneNumber" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/location": { "post": { "operationId": "send_location", "summary": "Enviar Ubicación", "description": "Envía una ubicación geográfica con pin en el mapa. El destinatario puede abrirla directamente en Google Maps o Apple Maps.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "latitude": { "description": "Latitud", "type": "number", "example": -23.5505 }, "longitude": { "description": "Longitud", "type": "number", "example": -46.6333 }, "name": { "description": "Nombre del lugar", "type": "string", "example": "Sede da empresa" }, "address": { "description": "Dirección", "type": "string", "example": "Av. Paulista, 1000 - São Paulo" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "latitude", "longitude" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/location-button": { "post": { "operationId": "send_location_button", "summary": "Solicitar Ubicación", "description": "Envía un mensaje con un botón que pide la ubicación del usuario. El botón de compartir ubicación se agrega automáticamente.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "text": { "description": "Texto del mensaje", "type": "string", "example": "Compartilhe sua localização para entregarmos seu pedido:" }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "text" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/media": { "post": { "operationId": "send_media", "summary": "Enviar Multimedia", "description": "Envía un archivo multimedia a un contacto. El archivo debe estar accesible en una URL pública.\n\nTipos disponibles:\n• image: Imagen (JPG, PNG, GIF, WebP). Admite pie de foto mediante text.\n• video: Video (MP4, AVI, MOV). Admite pie de foto mediante text.\n• audio: Audio como archivo (MP3, OGG, WAV). Aparece con ícono de archivo de audio.\n• ptt: Push-to-Talk: audio que aparece como mensaje de voz (burbuja de micrófono). Ideal para humanizar automatizaciones.\n• myaudio: Audio nativo de WhatsApp (OGG/Opus). Similar a ptt, úsalo cuando ya tengas el archivo en el formato correcto.\n• ptv: Mensaje de video (nota de video redonda). Siempre llega en formato circular; el video 16:9 se recorta en el centro. Ignora el pie de foto (el campo text no aparece). Usa MP4 H.264. Acepta duraciones largas (probado de 15 a 180 s) y tamaño dentro del límite de multimedia.\n• document: Documento (PDF, DOCX, XLSX, etc.). Usa docName para definir el nombre mostrado en el chat.\n• sticker: Sticker animado o estático (WebP).\n\nLímite de tamaño (envío por URL): imagen, video y audio hasta ~190 MB; documento hasta ~500 MB. Por encima de eso WhatsApp lo rechaza (HTTP 413 / error de carga). Nota: al enviar el archivo en base64 en el cuerpo de la solicitud por la API pública (/api/v1), el límite baja a ~2 MB. Por eso, para archivos más grandes, envía siempre por URL.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "type": { "description": "Tipo de multimedia", "type": "string", "enum": [ "image", "video", "videoplay", "audio", "ptt", "myaudio", "ptv", "document", "sticker" ], "default": "image" }, "file": { "description": "URL del archivo", "type": "string", "example": "https://..." }, "text": { "description": "Pie de foto: imágenes y videos", "type": "string", "example": "Descrição da mídia" }, "mentions": { "description": "Etiquetar miembros (solo grupo)", "type": "string", "example": "all" }, "docName": { "description": "Nombre del archivo: obligatorio para document", "type": "string", "example": "arquivo.pdf" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "type", "file" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/buttons": { "post": { "operationId": "send_buttons", "summary": "Enviar Botones de Respuesta", "description": "Envía botones clicables (hasta 3). Cada objeto del array `buttons` se convierte en un tipo de botón distinto según el campo usado:\n\n• `text` + `id` → botón de respuesta rápida (el contacto lo toca y se envía el texto)\n• `text` + `url` → botón que abre un enlace externo\n• `text` + `phone` → botón de llamada\n• `text` + `copy` → botón que copia un código al portapapeles\n\nSin `image`, el mensaje sale solo con texto + botones (encabezado limpio). Con `image`, aparece una imagen en la parte superior. Limitación de WhatsApp: mezclar reply con url/phone/copy en el mismo mensaje puede mostrar el aviso 'Abrir en el celular'.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del destinatario (con código de país)", "type": "string", "example": "5511999999999" }, "text": { "description": "Texto del mensaje", "type": "string", "example": "Como podemos ajudar?" }, "buttons": { "description": "Botones (hasta 3). Usa text+id para reply, text+url para enlace, text+phone para llamar, text+copy para copiar un código", "example": [ { "text": "Sim", "id": "yes" }, { "text": "Nosso site", "url": "https://exemplo.com" }, { "text": "Ligar", "phone": "+5511999999999" } ] }, "image": { "description": "URL de la imagen en la parte superior (opcional)", "type": "string", "example": "https://exemplo.com/banner.jpg" }, "footer": { "description": "Texto del pie (opcional)", "type": "string", "example": "Escolha uma opção" }, "delay": { "description": "Retraso en ms antes de enviar (opcional)", "type": "number", "example": 1200 }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "text", "buttons" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "InteractiveMessage", "status": "Pending" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/list": { "post": { "operationId": "send_list", "summary": "Enviar Lista de Opciones", "description": "Envía un menú en lista con secciones y elementos seleccionables. El contacto toca el botón y elige una opción.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del destinatario", "type": "string", "example": "5511999999999" }, "text": { "description": "Texto principal", "type": "string", "example": "Escolha uma opção:" }, "choices": { "description": "Opciones: usa \"[Sección]\" para el encabezado y \"Item|id|descripción\" para cada elemento", "example": [ "[Produtos]", "Camiseta|p1|R$ 50", "Calça|p2|R$ 120" ] }, "listButton": { "description": "Texto del botón que abre la lista", "type": "string", "example": "Ver opções" }, "footerText": { "description": "Pie (opcional)", "type": "string" }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "text", "choices" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "ListMessage", "status": "Pending" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/poll": { "post": { "operationId": "send_poll", "summary": "Enviar Encuesta", "description": "Envía una encuesta nativa de WhatsApp. Los contactos votan y el resultado llega por webhook.\n\nEncuesta (type poll): usa choices (lista de opciones) y selectableCount (cuántas puede marcar el usuario; >1 = opción múltiple). WhatsApp acepta 12+ opciones. Los votos llegan por el webhook de mensajes como PollUpdateMessage con el campo vote ya descifrado (texto de la opción); en opción múltiple llega la lista de las opciones actuales separada por comas, y un voto removido llega vacío.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del destinatario", "type": "string", "example": "5511999999999" }, "text": { "description": "Pregunta de la encuesta", "type": "string", "example": "Qual o melhor dia?" }, "choices": { "description": "Opciones de voto (array de strings)", "example": [ "Segunda", "Terça", "Quarta" ] }, "selectableCount": { "description": "Votos permitidos por persona (0 = ilimitado)", "type": "string", "default": "1" }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "text", "choices" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "PollCreationMessage", "status": "Pending" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/pix-button": { "post": { "operationId": "send_pix_button", "summary": "Enviar Botón PIX", "description": "Envía un botón de pago PIX nativo de WhatsApp. El contacto puede copiar la clave y pagar directamente.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "ID del chat al que se enviará el mensaje. Puede ser un número de teléfono en formato internacional, un ID de grupo (`@g.us`), un ID de usuario (con `@s.whatsapp.net` o `@lid`).", "type": "string", "example": "5511999999999" }, "pixType": { "description": "Tipo de clave PIX. Valores aceptados: CPF, CNPJ, PHONE, EMAIL o EVP", "type": "string", "enum": [ "EMAIL", "CPF", "CNPJ", "PHONE", "EVP" ], "example": "EVP" }, "pixKey": { "description": "Valor de la clave PIX (CPF/CNPJ/teléfono/email/EVP)", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "pixName": { "description": "Nombre mostrado como receptor del PIX (por defecto \"Pix\" si está vacío)", "type": "string", "example": "Loja Exemplo" }, "async": { "description": "Encola el envío para procesamiento asíncrono", "type": "boolean" }, "delay": { "description": "Retraso en milisegundos antes del envío (muestra \"escribiendo...\" en WhatsApp)", "type": "number", "example": 1200 }, "readchat": { "description": "Marca el chat como leído después de enviar el mensaje", "type": "boolean" }, "readmessages": { "description": "Marca los mensajes recientes como leídos después del envío", "type": "boolean" }, "replyid": { "description": "ID del mensaje que se responderá", "type": "string" }, "mentions": { "description": "Lista de números mencionados separados por coma", "type": "string" }, "track_source": { "description": "Origen de rastreo (ej.: chatwoot, crm-interno)", "type": "string" }, "track_id": { "description": "Identificador de rastreo (acepta valores duplicados)", "type": "string" }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "pixType", "pixKey" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/request-payment": { "post": { "operationId": "send_request_payment", "summary": "Solicitar Pago", "description": "Envía una solicitud de pago con el botón nativo \"Revisar y pagar\" de WhatsApp. Es obligatorio enviar al menos un método de pago: `pixKey`, `boletoCode`, `paymentLink` o `allowCards: true`. Sin eso, la API devuelve error.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "amount": { "description": "Monto (BRL)", "type": "number", "example": 49.9 }, "pixKey": { "description": "Clave PIX (CPF/CNPJ/teléfono/email/EVP)", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "pixType": { "description": "Tipo de clave PIX", "type": "string", "enum": [ "EVP", "CPF", "CNPJ", "PHONE", "EMAIL" ], "default": "EVP" }, "itemName": { "description": "Nombre del ítem", "type": "string", "example": "Assinatura Plano Ouro" }, "invoiceNumber": { "description": "Número de factura", "type": "string", "example": "PED-123" }, "title": { "description": "Título del flujo", "type": "string", "example": "Detalhes do pedido" }, "footer": { "description": "Pie", "type": "string", "example": "Loja Exemplo" }, "pixName": { "description": "Nombre del receptor (por defecto: nombre del perfil)", "type": "string", "example": "Loja Exemplo" }, "text": { "description": "Texto del mensaje", "type": "string", "example": "Pagamento referente ao pedido #123" }, "paymentLink": { "description": "Enlace de pago externo", "type": "string", "example": "https://pagamento.exemplo.com/123" }, "fileUrl": { "description": "URL del archivo adjunto", "type": "string", "example": "https://..." }, "fileName": { "description": "Nombre del archivo adjunto", "type": "string", "example": "boleto.pdf" }, "boletoCode": { "description": "Código del boleto", "type": "string", "example": "34191.79001 01043.510047 91020.150008 8 87350026000" }, "allowCards": { "description": "Permitir tarjeta", "type": "boolean" }, "currency": { "description": "Moneda", "type": "string", "example": "BRL" }, "note": { "description": "Nota / Observación", "type": "string", "example": "Pagamento referente ao pedido #123" }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "amount" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/status": { "post": { "operationId": "send_status", "summary": "Enviar Estado / Story", "description": "Publica un estado/story en WhatsApp (texto, imagen o video). Visible para todos los contactos durante 24 horas.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Tipo", "type": "string", "enum": [ "text", "image", "video", "audio", "ptt" ], "default": "text" }, "text": { "description": "Texto (para tipo texto)", "type": "string", "example": "Olá mundo!" }, "background_color": { "description": "Color de fondo (solo tipo texto)", "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19" ], "default": "19" }, "font": { "description": "Fuente (solo tipo texto)", "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8" ], "default": "0" }, "file": { "description": "URL del archivo (imagen/video/audio)", "type": "string", "example": "https://..." } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/send/text": { "post": { "operationId": "send_text", "summary": "Enviar Texto", "description": "Envía un mensaje de texto simple a un número de WhatsApp. El número debe incluir el código de país, por ejemplo: 5511999999999.", "tags": [ "Enviar Mensajes" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "text": { "description": "Mensaje", "type": "string", "example": "Olá! Tudo bem?" }, "mentions": { "description": "Etiquetar miembros (solo grupo)", "type": "string", "example": "all" }, "delay": { "description": "Delay (ms)", "type": "number", "example": 1200 }, "replyid": { "description": "ID del mensaje a responder", "type": "string", "example": "ABCDEF123456" }, "digitando": { "description": "Muestra un indicador automático de \"escribiendo...\" proporcional al tamaño del mensaje antes de enviarlo. Activado por defecto (humaniza y reduce el riesgo de bloqueo). Envía false para desactivarlo y responder más rápido. La respuesta sigue siendo síncrona.", "type": "boolean" } }, "required": [ "number", "text" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageId": "ABCDEF123456", "status": "sent" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/archive": { "post": { "operationId": "chat_archive", "summary": "Archivar Chat", "description": "Archiva una conversación, ocultándola de la lista principal de WhatsApp.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número o JID del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "archive": { "description": "Archivar", "type": "boolean", "default": true } }, "required": [ "number", "archive" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/block": { "post": { "operationId": "chat_block", "summary": "Bloquear / Desbloquear Contacto", "description": "⚠️ ATENCIÓN: Bloquea un contacto. NO uses block: false . puede DESCONECTAR toda la instancia (bug conocido de WhatsApp). Para desbloquear, usa WhatsApp directamente.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "block": { "description": "Acción", "type": "boolean", "default": true } }, "required": [ "number", "block" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Blocked successfully", "blockList": [ "5511999999999@s.whatsapp.net" ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/blocklist": { "get": { "operationId": "chat_blocklist", "summary": "Lista de Bloqueados", "description": "Devuelve todos los contactos bloqueados por la instancia.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "blocked": [ "5511999999999@s.whatsapp.net" ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/delete": { "post": { "operationId": "chat_delete", "summary": "Eliminar Chat", "description": "Elimina un chat completo. Puede limpiar solo en la app o también en la base de datos.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del chat en formato internacional.\nPara grupos usa el ID completo del grupo.\n", "type": "string", "example": "5511999999999" }, "deleteChatDB": { "description": "Si es true, elimina el chat de la base de datos", "type": "boolean", "example": false }, "deleteMessagesDB": { "description": "Si es true, elimina todos los mensajes del chat de la base de datos", "type": "boolean", "example": false }, "deleteChatWhatsApp": { "description": "Si es true, elimina el chat de WhatsApp.\nPara grupos, esta operación no está permitida y el chat solo se vaciará.\n", "type": "boolean", "example": false }, "clearChatWhatsApp": { "description": "Si es true, vacía la conversación del chat en WhatsApp (sin salir del chat).\nFunciona para grupos y conversaciones individuales.\n", "type": "boolean", "example": false } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "actions": [], "response": "Chat deletion process completed" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/find": { "post": { "operationId": "chat_find", "summary": "Buscar Chats", "description": "Busca chats con filtros avanzados: por nombre, label, estado, grupo y más.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "operator": { "description": "Operador lógico entre los filtros", "type": "string", "enum": [ "AND", "OR" ] }, "sort": { "description": "Orden (+/- campo, ej: -wa_lastMsgTimestamp)", "type": "string", "example": "-wa_lastMsgTimestamp" }, "limit": { "description": "Cantidad máxima de resultados a devolver", "type": "number" }, "offset": { "description": "Número de registros a omitir (para paginación)", "type": "number" }, "wa_fastid": { "description": "ID interno del chat", "type": "string" }, "wa_chatid": { "description": "ID del chat en WhatsApp", "type": "string" }, "wa_archived": { "description": "¿Archivado?", "type": "boolean" }, "wa_contactName": { "description": "Nombre del contacto", "type": "string" }, "wa_name": { "description": "Nombre en WhatsApp", "type": "string" }, "name": { "description": "Nombre", "type": "string" }, "wa_isBlocked": { "description": "¿Bloqueado?", "type": "boolean" }, "wa_isGroup": { "description": "¿Es grupo?", "type": "boolean" }, "wa_isGroup_admin": { "description": "¿Es admin del grupo?", "type": "boolean" }, "wa_isGroup_announce": { "description": "¿Grupo solo para admins?", "type": "boolean" }, "wa_isGroup_member": { "description": "¿Es miembro del grupo?", "type": "boolean" }, "wa_isPinned": { "description": "¿Fijado?", "type": "boolean" }, "wa_label": { "description": "ID de la label aplicada al chat. Usa el valor devuelto por `/labels`, no el nombre de la etiqueta.", "type": "string" }, "wa_notes": { "description": "¿Tiene notas?", "type": "string" }, "lead_tags": { "description": "Tags del lead", "type": "string" }, "lead_isTicketOpen": { "description": "¿Ticket abierto?", "type": "boolean" }, "lead_assignedAttendant_id": { "description": "ID del agente", "type": "string" }, "lead_status": { "description": "Estado del lead", "type": "string" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "chats": [ { "jid": "5511999999999@s.whatsapp.net", "name": "João", "unreadCount": 3 } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/mute": { "post": { "operationId": "chat_mute", "summary": "Silenciar Chat", "description": "Silencia las notificaciones de una conversación por un período en milisegundos. Ejemplo: 86400000 = 24h.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número o JID del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "duration": { "description": "Duración (ms): ej: 86400000 = 24h", "type": "number", "example": 86400000 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/notes": { "post": { "operationId": "chat_notes", "summary": "Ver Notas del Chat", "description": "Devuelve las notas internas (privadas) asociadas a un chat.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "JID completo del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "notes": "Notas internas do chat" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/notes/edit": { "post": { "operationId": "chat_notes_edit", "summary": "Editar Notas del Chat", "description": "Edita las notas internas de un chat. Las notas solo son visibles para ti.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "JID completo del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "notes": { "description": "Contenido de la nota a guardar en el chat", "type": "string", "example": "Cliente prefere contato no período da tarde" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/notes/refresh": { "post": { "operationId": "chat_notes_refresh", "summary": "Recargar Notas", "description": "Recarga las notas internas de WhatsApp en la base de datos local.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "JID completo del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "force": { "description": "Prueba primero con `false`.\nUsa `true` solo cuando la recarga estándar no funcione bien,\nya que este modo hace una nueva lectura más completa de las notas.\n", "type": "boolean", "example": false } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/pin": { "post": { "operationId": "chat_pin", "summary": "Fijar / Desfijar Chat", "description": "Fija o desfija una conversación en la parte superior de la lista de chats de WhatsApp.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número o JID del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "pin": { "description": "Acción", "type": "boolean", "default": true } }, "required": [ "number", "pin" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/read": { "post": { "operationId": "chat_read", "summary": "Marcar Chat como Leído", "description": "Marca todos los mensajes no leídos de una conversación como leídos, reiniciando el contador de no leídos.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número o JID del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/delete": { "post": { "operationId": "message_delete", "summary": "Eliminar Mensaje", "description": "Elimina un mensaje enviado para todos los participantes del chat. Solo es posible eliminar mensajes enviados por la propia instancia.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del mensaje", "type": "string", "example": "ABCDEF123456" }, "number": { "description": "Número del destinatario", "type": "string", "example": "5511999999999" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Timestamp": "2026-04-06T04:50:40Z", "ID": "3EB0C6074918E013090475", "Sender": "..." } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/download": { "post": { "operationId": "message_download", "summary": "Descargar Multimedia", "description": "Descarga un archivo multimedia recibido (imagen, video, audio, documento) a partir del ID del mensaje. El campo `id` debe venir del webhook o del endpoint `/message/find`. Nota: el parámetro transcribe es best-effort y puede no devolver la transcripción. Para una transcripción garantizada de audios, usa el módulo de IA.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del mensaje", "type": "string", "example": "7EB0F01D7244B421048F0706368376E0" }, "return_link": { "description": "Devolver URL pública del archivo", "type": "boolean", "default": true }, "return_base64": { "description": "Devolver archivo en base64", "type": "boolean", "default": false }, "generate_mp3": { "description": "Para audios: devolver como MP3 (false = OGG)", "type": "boolean", "default": true }, "transcribe": { "description": "Transcribir audio (best-effort: puede no devolver texto)", "type": "boolean", "default": false } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "fileURL": "https://server.example.com/files/abc123.jpg", "mimetype": "image/jpeg" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/edit": { "post": { "operationId": "message_edit", "summary": "Editar Mensaje", "description": "Edita el texto de un mensaje enviado previamente. Aparece con un indicador de editado para el destinatario. Solo funciona con mensajes enviados por la propia instancia.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del mensaje", "type": "string", "example": "ABCDEF123456" }, "number": { "description": "Número del destinatario", "type": "string", "example": "5511999999999" }, "text": { "description": "Nuevo texto", "type": "string", "example": "Texto corrigido..." } }, "required": [ "id", "number", "text" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "3EB0BB655F4F2AFA22FDE3", "messageType": "ExtendedTextMessage", "messageTimestamp": 1775450980468, "status": "Pending" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/find": { "post": { "operationId": "message_find", "summary": "Historial de Mensajes", "description": "Devuelve el historial de mensajes de la instancia. Filtra por `chatid` para buscar mensajes de una conversación específica. Admite paginación mediante `limit` y `offset`.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "chatid": { "description": "ID del chat (JID)", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "id": { "description": "ID de un mensaje específico", "type": "string", "example": "ABCDEF123456" }, "limit": { "description": "Límite (predeterminado: 100)", "type": "number", "example": 100 }, "offset": { "description": "Offset (paginación)", "type": "number", "example": 0 } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messages": [], "total": 0 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/history-sync": { "post": { "operationId": "message_history_sync", "summary": "Sincronizar Historial", "description": "Solicita la sincronización del historial de mensajes antiguos de un chat. Los mensajes llegan por webhook/SSE.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "messageid": { "description": "ID del mensaje de referencia usado para buscar mensajes más antiguos del chat", "type": "string", "example": "3EB01234567890ABCDEF" }, "number": { "description": "JID completo del chat", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "count": { "description": "Cantidad deseada de mensajes en la sincronización", "type": "number", "example": 20 } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "count": 50 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/markread": { "post": { "operationId": "message_markread", "summary": "Marcar como Leído", "description": "Marca uno o más mensajes como leídos. Envía un array de IDs.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "IDs de los mensajes", "example": [ "3EB0538DA65A59F6D8A251" ] } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "message_id": "5511999990000:3EB0CECA26BF34A157FC71", "status": "success" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/presence": { "post": { "operationId": "message_presence", "summary": "Indicador de Escribiendo...", "description": "Muestra \"escribiendo...\" o \"grabando audio...\" al contacto. El indicador desaparece automáticamente después de unos segundos.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "presence": { "description": "Tipo", "type": "string", "enum": [ "composing", "recording", "paused" ], "default": "composing" }, "delay": { "description": "Duración (ms, máx. 300000)", "type": "number", "example": 3000 } }, "required": [ "number", "presence" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "ok" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/react": { "post": { "operationId": "message_react", "summary": "Reaccionar con Emoji", "description": "Envía una reacción (emoji) a un mensaje existente. Envía un emoji vacío para QUITAR la reacción. El id debe ser el messageId aplanado en el formato OWNER:MSGID (ej: 5511999990000:2A6E2F02CE4125FDBA1B): no uses el formato Baileys concatenado con el JID, devolverá 404. El webhook de confirmación llega con messageType=ReactionMessage e incluye el atajo 'reaction' en el envelope.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del contacto", "type": "string", "example": "5511999999999" }, "id": { "description": "ID del mensaje (formato OWNER:MSGID)", "type": "string", "example": "5511999990000:2A6E2F02CE4125FDBA1B" }, "emoji": { "description": "Emoji de la reacción (vacío = quitar): alias: text", "type": "string", "example": "👍" } }, "required": [ "number", "id", "emoji" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messageType": "ReactionMessage", "status": "Pending" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/ephemeral": { "post": { "operationId": "chat_ephemeral", "summary": "Mensajes Temporales (conversación privada)", "description": "Activa o desactiva los mensajes temporales (que desaparecen solos) en una conversación privada. Se aplica a los próximos mensajes de la conversación. Duración en segundos, siguiendo el estándar de WhatsApp: 0 lo desactiva, 86400 = 24 horas, 604800 = 7 días, 7776000 = 90 días.", "tags": [ "Conversaciones" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del contacto (con código de país)", "type": "string", "example": "5511999999999" }, "duration": { "description": "Duración antes de desaparecer", "type": "string", "enum": [ "0", "86400", "604800", "7776000" ] } }, "required": [ "number", "duration" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/check": { "post": { "operationId": "check_number", "summary": "Verificar Número", "description": "Verifica si uno o más números están registrados en WhatsApp. Devuelve JID, nombre verificado y estado.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "description": "Números a verificar (array)", "type": "string", "example": "[\"5511999999999\", \"5521888888888\"]" } }, "required": [ "numbers" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "query": "5511999999999", "isInWhatsapp": true, "jid": "5511999999999@s.whatsapp.net" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/details": { "post": { "operationId": "chat_details", "summary": "Detalles del Contacto", "description": "Devuelve los detalles completos de un contacto: nombre, foto, estado, verificación, e-commerce.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número de teléfono o ID del grupo", "type": "string", "example": "5511999999999" }, "preview": { "description": "Controla el tamaño de la imagen de perfil devuelta:\n- `true`: Devuelve la imagen en tamaño preview (menor, optimizada para listados)\n- `false` (predeterminado): Devuelve la imagen en tamaño completo (resolución original, mayor calidad)\n", "type": "boolean" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "jid": "5511999999999@s.whatsapp.net", "name": "João", "pushName": "João Silva", "profilePicUrl": "https://..." } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/contact/add": { "post": { "operationId": "contact_add", "summary": "Agregar Contacto", "description": "Agrega un nuevo contacto a la agenda del WhatsApp conectado con nombre y número.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "description": "Teléfono (con código de país)", "type": "string", "example": "5511999999999" }, "name": { "description": "Nombre completo", "type": "string", "example": "João Silva" } }, "required": [ "phone", "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/contact/remove": { "post": { "operationId": "contact_remove", "summary": "Eliminar Contacto", "description": "Elimina un contacto de la agenda de WhatsApp.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número de teléfono en formato internacional con código de país obligatorio. \nPara Brasil, debe comenzar con 55. Acepta variaciones con/sin símbolo +, \ncon/sin paréntesis, con/sin guion y con/sin espacios. También acepta el formato \nJID de WhatsApp (@s.whatsapp.net). No acepta contactos comerciales (@lid) \nni grupos (@g.us).\n", "type": "string", "example": "5511999999999" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/contacts": { "get": { "operationId": "contacts_get", "summary": "Listar Contactos (Rápido)", "description": "Lista todos los contactos guardados en la agenda de WhatsApp.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "jid": "5511999999999@s.whatsapp.net", "name": "João" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/contacts/list": { "post": { "operationId": "find_contacts", "summary": "Listar Contactos", "description": "Busca contactos con paginación. Usa limit y offset para navegar.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "Límite", "type": "number", "example": 50 }, "offset": { "description": "Offset", "type": "number", "example": 0 } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "contacts": [ { "jid": "5511999999999@s.whatsapp.net", "contact_name": "João Silva" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/profile/image": { "post": { "operationId": "profile_image", "summary": "Cambiar Foto", "description": "Cambia la imagen de perfil de tu instancia. Envía una URL, base64 o \"remove\" para quitarla.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "description": "URL, base64 o \"remove\"", "type": "string", "example": "https://exemplo.com/logo.jpg" } }, "required": [ "image" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/profile/name": { "post": { "operationId": "profile_name", "summary": "Cambiar Nombre", "description": "Cambia el nombre del perfil de tu instancia en WhatsApp.", "tags": [ "Contactos y Perfil" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Nuevo nombre (máx. 25 caracteres)", "type": "string", "example": "Minha Empresa" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/community/create": { "post": { "operationId": "community_create", "summary": "Crear comunidad", "description": "Crea una Comunidad de WhatsApp, una estructura que agrupa varios grupos bajo un único canal central de anuncios. El número conectado será el propietario de la comunidad.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Nombre de la comunidad", "type": "string", "example": "Comunidade da Empresa" }, "description": { "description": "Descripción", "type": "string", "example": "Descrição da comunidade" }, "participants": { "description": "Participantes (números con código de país)", "example": [ "5511999999999" ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "JID": "120363000000000001@g.us", "Name": "Comunidade da Empresa", "IsParent": true, "DefaultSubGroupId": "120363000000000002@g.us", "Participants": [ { "JID": "...", "IsAdmin": true, "IsSuperAdmin": true } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/community/editgroups": { "post": { "operationId": "community_editgroups", "summary": "Gestionar grupos de la comunidad", "description": "Agrega o elimina grupos de una comunidad existente. Usa action: add o action: remove con el array de JIDs de grupos.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "community": { "description": "JID de la comunidad", "type": "string", "example": "120363000000000001@g.us" }, "action": { "description": "Acción", "type": "string", "enum": [ "add", "remove" ], "default": "add" }, "groups": { "description": "JIDs de los grupos (JSON array)", "example": [ "120363000000000000@g.us" ] } }, "required": [ "community", "action", "groups" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "failed": null, "message": "community updated", "success": null } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/create": { "post": { "operationId": "create_group", "summary": "Crear grupo", "description": "Crea un nuevo grupo de WhatsApp con los participantes indicados. El número conectado se agrega automáticamente como administrador. Nombre: mín. 1, máx. 100 caracteres. Máximo de 50 participantes.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Nombre del grupo", "type": "string", "example": "Meu Time" }, "participants": { "description": "Participantes (JSON array de números con código de país)", "type": "string", "example": "[\"5511999990001\",\"5511999990002\"]" } }, "required": [ "name", "participants" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "groupJID": "120363000000000000@g.us", "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/info": { "post": { "operationId": "group_info", "summary": "Información del grupo", "description": "Devuelve los detalles completos de un grupo: nombre, descripción, participantes, administradores, fecha de creación y configuración. Usa `getInviteLink: true` para incluir el enlace de invitación en la respuesta.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "getInviteLink": { "description": "Incluir enlace de invitación", "type": "boolean", "default": false } }, "required": [ "groupjid" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "120363000000000000@g.us", "name": "Meu Grupo", "description": "Descrição", "inviteLink": "https://chat.whatsapp.com/...", "participants": [ { "id": "5511...@s.whatsapp.net", "isAdmin": true } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/inviteInfo": { "post": { "operationId": "group_inviteInfo", "summary": "Información por invitación", "description": "Obtiene información de un grupo a partir del código o enlace de invitación.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invitecode": { "description": "Código de invitación o URL completa del grupo.\nPuede ser un código corto o la URL completa de WhatsApp.\n", "type": "string" } }, "required": [ "invitecode" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "jid": "120363000000000000@g.us", "name": "Meu Grupo", "size": 15 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/join": { "post": { "operationId": "group_join", "summary": "Unirse a un grupo por enlace", "description": "Hace que la instancia se una a un grupo mediante un enlace de invitación de WhatsApp. Acepta la URL completa (https://chat.whatsapp.com/...) o solo el código.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invitecode": { "description": "Código o URL de invitación", "type": "string", "example": "https://chat.whatsapp.com/XXXXXXXXXXXXXXXX" } }, "required": [ "invitecode" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "groupJID": "120363000000000000@g.us" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/leave": { "post": { "operationId": "leave_group", "summary": "Salir del grupo", "description": "Quita el número conectado del grupo especificado. El sistema no puede deshacer esta acción. También sirve para salir de comunidades.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" } }, "required": [ "groupjid" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Group leave successful" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/list": { "get": { "operationId": "list_groups", "summary": "Listar grupos", "description": "Lista todos los grupos de WhatsApp. Devuelve un array con el JID, el nombre y los datos de cada grupo.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "groups": [ { "id": "120363000000000000@g.us", "name": "Meu Grupo" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "post": { "operationId": "group_list", "summary": "Buscar grupos", "description": "Lista grupos con la opción de incluir participantes. Devuelve un objeto con un array \"groups\".", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "getParticipants": { "description": "Incluir participantes", "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/resetInviteCode": { "post": { "operationId": "group_reset_invite", "summary": "Restablecer código de invitación", "description": "Genera un nuevo código de invitación para el grupo. El enlace anterior quedará invalidado.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" } }, "required": [ "groupjid" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "InviteLink": "https://chat.whatsapp.com/YYYYYYYYYYYYYYYY" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateAnnounce": { "post": { "operationId": "group_update_announce", "summary": "Modo solo administradores", "description": "Activa o desactiva el modo en que solo los administradores pueden enviar mensajes. Ideal para canales de comunicación unidireccional.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "announce": { "description": "Solo administradores", "type": "boolean", "default": true } }, "required": [ "groupjid", "announce" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateDescription": { "post": { "operationId": "group_update_description", "summary": "Cambiar descripción del grupo", "description": "Cambia la descripción del grupo. No se permite una descripción vacía.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "description": { "description": "Nueva descripción (máx. 512 caracteres)", "type": "string", "example": "Descrição do grupo..." } }, "required": [ "groupjid", "description" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateImage": { "post": { "operationId": "group_update_image", "summary": "Cambiar foto del grupo", "description": "Cambia la imagen del grupo. Envía la URL de la imagen o \"remove\" para quitarla.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "image": { "description": "URL, base64 o \"remove\"", "type": "string", "example": "https://exemplo.com/foto.jpg ou \"remove\"" } }, "required": [ "groupjid", "image" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateLocked": { "post": { "operationId": "group_update_locked", "summary": "Bloquear edición del grupo", "description": "Cuando está activado, solo los administradores pueden cambiar el nombre, la foto y la descripción del grupo.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "locked": { "description": "Bloquear edición", "type": "boolean", "default": true } }, "required": [ "groupjid", "locked" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateName": { "post": { "operationId": "group_update_name", "summary": "Renombrar grupo", "description": "Cambia el nombre visible del grupo. Mín. 1 y máx. 25 caracteres. Requiere que el número conectado sea administrador.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "name": { "description": "Nuevo nombre (máx. 25 caracteres)", "type": "string", "example": "Nome do grupo" } }, "required": [ "groupjid", "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateParticipants": { "post": { "operationId": "group_participants", "summary": "Gestionar participantes", "description": "Gestiona los participantes del grupo. Agregar, eliminar, promover o degradar.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "ID del grupo (@g.us)", "type": "string", "example": "120363000000000000@g.us" }, "action": { "description": "Acción", "type": "string", "enum": [ "add", "remove", "promote", "demote", "approve", "reject" ], "default": "add" }, "participants": { "description": "Participantes (JSON array de números con código de país)", "type": "string", "example": "[\"5511999990003\"]" } }, "required": [ "groupjid", "action", "participants" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/ephemeral": { "post": { "operationId": "group_ephemeral", "summary": "Mensajes temporales (grupo)", "description": "Activa o desactiva los mensajes temporales en el grupo. Duración en segundos, estándar de WhatsApp: 0 desactiva, 86400 = 24 horas, 604800 = 7 días, 7776000 = 90 días.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "JID del grupo", "type": "string", "example": "120363123456789012@g.us" }, "duration": { "description": "Duración antes de desaparecer", "type": "string", "enum": [ "0", "86400", "604800", "7776000" ] } }, "required": [ "groupjid", "duration" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateJoinApproval": { "post": { "operationId": "group_join_approval", "summary": "Exigir aprobación para unirse", "description": "Define si el ingreso de nuevos miembros al grupo necesita la aprobación de un administrador.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "JID del grupo", "type": "string", "example": "120363123456789012@g.us" }, "IsJoinApprovalRequired": { "description": "Exigir aprobación para unirse", "type": "boolean" } }, "required": [ "groupjid", "IsJoinApprovalRequired" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/group/updateMemberAddMode": { "post": { "operationId": "group_member_add_mode", "summary": "Quién puede agregar miembros", "description": "Define quién puede agregar nuevos miembros al grupo: solo administradores o cualquier participante.", "tags": [ "Grupos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupjid": { "description": "JID del grupo", "type": "string", "example": "120363123456789012@g.us" }, "MemberAddMode": { "description": "Quién puede agregar", "type": "string", "enum": [ "admin_add", "all_member_add" ] } }, "required": [ "groupjid", "MemberAddMode" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/admin/accept": { "post": { "operationId": "newsletter_admin_accept", "summary": "Aceptar invitación de administrador", "description": "Acepta una invitación para ser administrador de un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/admin/invite": { "post": { "operationId": "newsletter_admin_invite", "summary": "Invitar administrador del canal", "description": "Invita a un número a ser administrador de un canal. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/admin/remove": { "post": { "operationId": "newsletter_admin_remove", "summary": "Eliminar administrador del canal", "description": "Elimina a un administrador de un canal. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/admin/revoke": { "post": { "operationId": "newsletter_admin_revoke", "summary": "Revocar invitación de administrador", "description": "Revoca una invitación de administrador pendiente. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/create": { "post": { "operationId": "newsletter_create", "summary": "Crear canal", "description": "Crea un nuevo canal (newsletter) de WhatsApp.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Nombre", "type": "string", "example": "Canal de Promoções" }, "description": { "description": "Descripción", "type": "string", "example": "Ofertas e novidades da loja" }, "picture": { "description": "URL, base64 puro o data URI de la imagen del canal.", "type": "string", "example": "https://example.com/newsletter.png" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "jid": "120363...@newsletter" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/delete": { "post": { "operationId": "newsletter_delete", "summary": "Eliminar canal", "description": "Elimina un canal que administras.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/description": { "post": { "operationId": "newsletter_description", "summary": "Cambiar descripción del canal", "description": "Actualiza la descripción de un canal. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "description": { "description": "Descripción", "type": "string", "example": "Atualizações, ofertas e novidades" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/follow": { "post": { "operationId": "newsletter_follow", "summary": "Seguir canal", "description": "Sigue un canal para recibir sus publicaciones.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/info": { "post": { "operationId": "newsletter_info", "summary": "Información del canal", "description": "Obtiene información detallada de un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID numérico del canal. Si se envía sin dominio, se convertirá a `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID completo del canal.", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "name": "Meu Canal", "description": "...", "subscribers": 150 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/link": { "post": { "operationId": "newsletter_link", "summary": "Buscar canal por enlace", "description": "Busca información de un canal por el enlace/clave de invitación.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "description": "Clave de invitación del canal.", "type": "string", "example": "AbCdEfGhIjKlMn" } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "name": "Canal", "jid": "120363...@newsletter" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/list": { "get": { "operationId": "newsletter_list_get", "summary": "Listar canales", "description": "Lista todos los canales a los que está suscrita la instancia.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "newsletters": [] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/messages": { "post": { "operationId": "newsletter_messages", "summary": "Mensajes del canal", "description": "Obtiene los mensajes publicados en un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID numérico del canal. Si se envía sin dominio, se convertirá a `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID completo del canal.", "type": "string", "example": "120363123456789012@newsletter" }, "count": { "description": "Cantidad de mensajes/publicaciones a obtener.", "type": "number", "example": 20 }, "beforeid": { "description": "Devuelve los mensajes anteriores al `serverid` indicado.\nÚsalo para la paginación hacia atrás.\n", "type": "number", "example": 12345 } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messages": [] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/messages/delete": { "post": { "operationId": "newsletter_messages_delete", "summary": "Eliminar mensaje del canal", "description": "Elimina un mensaje de un canal que administras.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID numérico del canal. Si se envía sin dominio, se convertirá a `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID completo del canal.", "type": "string", "example": "120363123456789012@newsletter" }, "messageid": { "description": "ID lógico del mensaje en el canal.", "type": "string", "example": "3EB0B4302B3A8A52F7A1" }, "serverid": { "description": "Identificador secuencial de la publicación en el canal.", "type": "number", "example": 12345 }, "count": { "description": "Cantidad de mensajes obtenidos por página al localizar la publicación.", "type": "number", "example": 100 }, "maxpages": { "description": "Cantidad máxima de páginas consultadas al localizar la publicación.", "type": "number", "example": 5 } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/messages/edit": { "post": { "operationId": "newsletter_messages_edit", "summary": "Editar mensaje del canal", "description": "Edita un mensaje reciente de un canal que administras.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID numérico del canal. Si se envía sin dominio, se convertirá a `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID completo del canal.", "type": "string", "example": "120363123456789012@newsletter" }, "messageid": { "description": "ID lógico del mensaje en el canal.", "type": "string", "example": "3EB0B4302B3A8A52F7A1" }, "serverid": { "description": "Identificador secuencial de la publicación en el canal.", "type": "number", "example": 12345 }, "text": { "description": "Nuevo texto o nueva leyenda de la publicación.", "type": "string", "example": "Post atualizado" }, "count": { "description": "Cantidad de mensajes obtenidos por página al localizar la publicación.", "type": "number", "example": 100 }, "maxpages": { "description": "Cantidad máxima de páginas consultadas al localizar la publicación.", "type": "number", "example": 5 } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/mute": { "post": { "operationId": "newsletter_mute", "summary": "Silenciar canal", "description": "Silencia las notificaciones de un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/name": { "post": { "operationId": "newsletter_name", "summary": "Cambiar nombre del canal", "description": "Actualiza el nombre de un canal. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "name": { "description": "Nombre", "type": "string", "example": "Canal de Promoções VIP" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/owner/transfer": { "post": { "operationId": "newsletter_owner_transfer", "summary": "Transferir propiedad del canal", "description": "Transfiere la propiedad del canal a otro número.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "phone": { "description": "Número (con código de país)", "type": "string", "example": "5511999999999" }, "quitAdmin": { "description": "Salir como administrador tras transferir", "type": "boolean", "example": false } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/picture": { "post": { "operationId": "newsletter_picture", "summary": "Cambiar foto del canal", "description": "Actualiza la foto de un canal. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "picture": { "description": "URL de la imagen", "type": "string", "example": "https://example.com/newsletter.png" } }, "required": [ "picture" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/reaction": { "post": { "operationId": "newsletter_reaction", "summary": "Reaccionar a una publicación del canal", "description": "Reacciona a una publicación de un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "serverid": { "description": "Server ID (número entero)", "type": "number", "example": 12345 }, "reaction": { "description": "Emoji de reacción", "type": "string", "example": "🔥" }, "reactionmessageid": { "description": "ID del mensaje de reacción", "type": "string", "example": "3EB0AABBCCDD" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/search": { "post": { "operationId": "newsletter_search", "summary": "Buscar canales", "description": "Busca canales públicos por texto, país o categoría.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "Límite de resultados", "type": "number", "example": 20 }, "view": { "description": "Tipo de visualización", "type": "string", "example": "RECOMMENDED" }, "countryCodes": { "description": "Códigos de país", "example": [ "BR" ] }, "searchText": { "description": "Texto de búsqueda", "type": "string", "example": "promo" }, "after": { "description": "Cursor (paginación)", "type": "string", "example": "YXJyYXljb25uZWN0aW9uOjE5" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/settings": { "post": { "operationId": "newsletter_settings", "summary": "Configuración del canal", "description": "Actualiza la configuración del canal (p. ej., códigos de reacción permitidos). (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "reactionCodes": { "description": "Códigos de reacción permitidos", "type": "string", "example": "basic" } }, "required": [ "reactionCodes" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/subscribe": { "post": { "operationId": "newsletter_subscribe", "summary": "Suscribirse a actualizaciones del canal", "description": "Se suscribe a actualizaciones temporales de un canal para recibir notificaciones.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/unfollow": { "post": { "operationId": "newsletter_unfollow", "summary": "Dejar de seguir", "description": "Deja de seguir un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/unmute": { "post": { "operationId": "newsletter_unmute", "summary": "Reactivar canal", "description": "Reactiva las notificaciones de un canal.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/updates": { "post": { "operationId": "newsletter_updates", "summary": "Actualizaciones del canal", "description": "Obtiene las actualizaciones de mensajes de un canal. (Nota: puede devolver un error GraphQL según la versión de WhatsApp)", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID numérico del canal. Si se envía sin dominio, se convertirá a `@newsletter`.", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID completo del canal.", "type": "string", "example": "120363123456789012@newsletter" }, "count": { "description": "Cantidad máxima de actualizaciones devueltas.", "type": "number", "example": 50 }, "afterid": { "description": "Devuelve solo las actualizaciones posteriores al `serverid` indicado.", "type": "number", "example": 12345 }, "since": { "description": "Timestamp de corte.\n- Si es mayor que `1000000000000`, se interpreta como milisegundos.\n- En caso contrario, se interpreta como segundos.\n", "type": "number", "example": 1710000000 } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/newsletter/viewed": { "post": { "operationId": "newsletter_viewed", "summary": "Marcar como visto", "description": "Marca las publicaciones del canal como vistas.", "tags": [ "Newsletters y Canales" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID", "type": "string", "example": "120363123456789012" }, "jid": { "description": "JID del canal/contacto", "type": "string", "example": "120363123456789012@newsletter" }, "serverids": { "description": "Server IDs (array de números enteros, p. ej., [1, 2, 3])", "example": [ 1, 2, 3 ] } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/advanced": { "post": { "operationId": "sender_advanced", "summary": "Enviar campaña en lote", "description": "Envía mensajes en lote con contenido individualizado por destinatario. Cada elemento del array messages puede tener un número y un texto distintos.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "description": "Mensajes (array de objetos)", "type": "string", "example": "[{\"number\":\"5511999999999\",\"text\":\"Olá!\"}]" }, "delayMin": { "description": "Retraso mínimo (segundos)", "type": "number", "example": 1 }, "delayMax": { "description": "Retraso máximo (segundos)", "type": "number", "example": 5 }, "folder_id": { "description": "ID de la carpeta", "type": "string", "example": "folder_abc123" }, "info": { "description": "Información adicional sobre la campaña", "type": "string", "example": "Campanha lancamento" }, "scheduled_for": { "description": "Programar para (timestamp en milisegundos o minutos a partir de ahora)", "type": "number", "example": 1 } }, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 1, "folder_id": "r5eb3b483c43f69", "status": "queued" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/clearall": { "delete": { "operationId": "sender_clearall_delete", "summary": "Limpiar toda la cola", "description": "Limpia toda la cola de mensajes, incluidos los pendientes y en curso.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "folders_deleted": 0, "messages_deleted": 0, "status": "processed" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/cleardone": { "post": { "operationId": "sender_cleardone", "summary": "Limpiar campañas completadas", "description": "Quita de la lista todas las campañas con estado completado dentro de la carpeta indicada.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "ID de la carpeta de campaña", "type": "string", "example": "folder_abc123" } }, "required": [ "folder_id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "cleanup started" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/edit": { "post": { "operationId": "sender_edit", "summary": "Controlar campaña", "description": "Controla una campaña de envío masivo: pausar, reanudar o cancelar.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "Identificador único de la campaña de envío", "type": "string", "example": "folder_123" }, "action": { "description": "Acción sobre la campaña", "type": "string", "enum": [ "stop", "continue", "delete" ], "example": "stop" } }, "required": [ "folder_id", "action" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Folder deletion has been initiated", "status": "deleting" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/listfolders": { "get": { "operationId": "sender_listfolders_get", "summary": "Listar campañas", "description": "Lista todas las campañas/carpetas de envío masivo. Devuelve un array directo.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "r5819c9fba43b98", "info": "", "status": "scheduled", "scheduled_for": 1775449285668, "delayMax": 3, "delayMin": 1, "log_delivered": 0, "log_failed": 0, "log_played": 0, "log_read": 0, "log_sucess": 0, "log_total": 1, "owner": "5511999999999" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/listmessages": { "post": { "operationId": "sender_listmessages", "summary": "Listar mensajes de la campaña", "description": "Devuelve los mensajes de una campaña específica con el estado de envío y paginación.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "description": "ID de la carpeta de campaña", "type": "string", "example": "folder_abc123" } }, "required": [ "folder_id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "messages": [ { "id": "5511999990000:3EB01C21C13D0C4BA33F40", "chatid": "5511999990000@s.whatsapp.net", "status": "Sent", "text": "Teste", "messageType": "Conversation", "send_folder_id": "r5819c9fba43b98" } ], "pagination": { "limit": 1000, "offset": 0, "totalRecords": 1 } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sender/simple": { "post": { "operationId": "sender_simple", "summary": "Enviar mensaje simple", "description": "Envía un mensaje a una lista de números con un retraso aleatorio entre cada envío. Devuelve un folder_id para el seguimiento.", "tags": [ "Campañas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "description": "Números (JSON array)", "type": "string", "example": "[\"5511999999999\",\"5511888888888\"]" }, "type": { "description": "Tipo de mensaje", "type": "string", "enum": [ "text", "image", "video", "document", "audio", "contact", "location" ], "default": "text" }, "text": { "description": "Texto del mensaje", "type": "string", "example": "Olá! Temos uma promoção..." }, "file": { "description": "URL del medio (si no es texto)", "type": "string", "example": "https://..." }, "folder": { "description": "Nombre de la campaña", "type": "string", "example": "promo-abril" }, "delayMin": { "description": "Retraso mínimo (segundos)", "type": "number", "example": 1 }, "delayMax": { "description": "Retraso máximo (segundos)", "type": "number", "example": 5 }, "scheduled_for": { "description": "Programar para (timestamp en milisegundos)", "type": "number", "example": 1775534400000 }, "info": { "description": "Información adicional sobre la campaña", "type": "string", "example": "Campanha Janeiro" } }, "required": [ "numbers", "type", "delayMin", "delayMax" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 1, "folder_id": "r37d5cc380a7f31", "status": "queued" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/call/make": { "post": { "operationId": "call_make", "summary": "Hacer llamada", "description": "Inicia una llamada de voz a un número de WhatsApp. La llamada suena en el destino, pero no establece comunicación de voz real.", "tags": [ "Llamadas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del contacto en formato internacional (ej: 5511999999999)", "type": "string", "example": "5511999999999" }, "call_duration": { "description": "Duración de la llamada en segundos. Pasado ese tiempo, la llamada se termina automáticamente.", "type": "number", "example": 15 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "call": { "callCreator": "5511999@s.whatsapp.net", "wasSentByAPI": true }, "response": "Call successful" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/call/reject": { "post": { "operationId": "call_reject", "summary": "Rechazar llamada", "description": "Rechaza una llamada entrante.", "tags": [ "Llamadas" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "(Opcional) Número del contacto en formato internacional (ej: 5511999999999)", "type": "string", "example": "5511999999999" }, "id": { "description": "(Opcional) ID único de la llamada a rechazar", "type": "string" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Call rejected" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/catalog/delete": { "post": { "operationId": "business_catalog_delete", "summary": "Eliminar producto del catálogo", "description": "Elimina permanentemente productos del catálogo de WhatsApp Business. Envía un array de IDs en el campo `productIds`. Atención: puede ocurrir un timeout (504) si los IDs son inválidos.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "description": "IDs de los productos (array)", "type": "string", "example": "[\"prod_abc123\"]" } }, "required": [ "productIds" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/catalog/hide": { "post": { "operationId": "business_catalog_hide", "summary": "Ocultar producto del catálogo", "description": "Oculta un producto del catálogo público sin eliminarlo. ⚠️ Puede devolver error 501 en cuentas que no admiten esta función. Es una limitación de WhatsApp, no de la API.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del producto", "type": "string", "example": "prod_abc123" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Product hidden" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/catalog/info": { "post": { "operationId": "business_catalog_info", "summary": "Información del producto", "description": "Devuelve información detallada de un producto específico del catálogo.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "description": "JID del catálogo a consultar", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "id": { "description": "El ID del producto.", "type": "string" } }, "required": [ "jid", "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "123", "name": "Produto", "price": 9990, "currency": "BRL" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/catalog/list": { "post": { "operationId": "business_catalog_list", "summary": "Listar catálogo de productos", "description": "Devuelve todos los productos registrados en el catálogo de WhatsApp Business del JID indicado.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "description": "JID del catálogo", "type": "string", "example": "5511999999999@s.whatsapp.net" } }, "required": [ "jid" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": [ { "id": "prod_abc123", "name": "Produto 1", "price": "49.90", "currency": "BRL" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/catalog/show": { "post": { "operationId": "business_catalog_show", "summary": "Mostrar producto en el catálogo", "description": "Hace visible un producto en el catálogo público de WhatsApp Business. ⚠️ Puede devolver error 501 en cuentas que no admiten esta función. Es una limitación de WhatsApp, no de la API.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del producto", "type": "string", "example": "prod_abc123" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Product shown" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/get/categories": { "get": { "operationId": "business_categories", "summary": "Listar categorías comerciales", "description": "Devuelve la lista de categorías disponibles para el perfil comercial de WhatsApp Business.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "categories": [ { "id": "1", "name": "Shopping and Retail" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/get/profile": { "post": { "operationId": "business_profile_get", "summary": "Ver perfil comercial", "description": "Devuelve los datos del perfil comercial de WhatsApp Business: descripción, dirección, correo electrónico, sitio web y categorías. Envía el `jid` con el número (sin @s.whatsapp.net). El número es obligatorio.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jid": { "description": "JID del contacto (obligatorio, ej: 5511999999999@s.whatsapp.net)", "type": "string", "example": "5511999999999" } }, "required": [ "jid" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": { "description": "Loja de produtos...", "address": "Av. Paulista, 1000", "email": "contato@empresa.com" } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/business/update/profile": { "post": { "operationId": "business_profile_update", "summary": "Actualizar perfil comercial", "description": "Actualiza los datos del perfil de WhatsApp Business. Es obligatorio enviar al menos uno de los campos: `description`, `address` o `email`. Atención: este endpoint puede devolver 403 forbidden si la instancia no es de tipo Business.", "tags": [ "WhatsApp Business" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "Descripción", "type": "string", "example": "Especialistas em automação WhatsApp" }, "address": { "description": "Dirección", "type": "string", "example": "Av. Paulista, 1000 - SP" }, "email": { "description": "Correo electrónico", "type": "string", "example": "contato@empresa.com" }, "websites": { "description": "Sitios web (array)", "type": "string", "example": "[\"https://empresa.com\"]" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/labels": { "post": { "operationId": "chat_labels", "summary": "Aplicar etiqueta al chat", "description": "Gestiona las etiquetas de un chat. Usa `labelids` para definir todas las etiquetas a la vez, `add_labelid` para agregar una etiqueta o `remove_labelid` para quitarla. Envía solo uno de estos campos por solicitud.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "description": "Número del contacto", "type": "string", "example": "5511999999999" }, "labelids": { "description": "IDs de las etiquetas (array, reemplaza todas)", "type": "string", "example": "[\"1\",\"2\"]" }, "add_labelid": { "description": "Agregar etiqueta (ID)", "type": "string", "example": "1" }, "remove_labelid": { "description": "Quitar etiqueta (ID)", "type": "string", "example": "1" } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Label added to chat" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/connect": { "post": { "operationId": "instance_connect", "summary": "Conectar instancia", "description": "Conecta la instancia a WhatsApp. Es necesario escanear el código QR después de esta llamada.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "description": "Número de teléfono en formato internacional (ej: 5511999999999). Si se informa, se genera un código de emparejamiento. Si se omite, se genera un código QR.", "type": "string", "example": "5511999999999" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "connected": true, "instance": { "id": "raa287d88df6336", "status": "connected", "name": "minha-instancia" }, "response": "Already connected", "status": { "connected": true, "loggedIn": true } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/disconnect": { "post": { "operationId": "instance_disconnect", "summary": "Desconectar instancia", "description": "Desconecta la instancia de WhatsApp. Será necesario escanear el código QR nuevamente para reconectar.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "info": "The device has been successfully disconnected from WhatsApp. A new QR code will be required for the next connection.", "instance": { "status": "disconnected", "lastDisconnect": "2026-04-06T04:56:41Z", "lastDisconnectReason": "disconnected by API" }, "response": "Disconnected" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/presence": { "post": { "operationId": "instance_presence", "summary": "Estado de presencia", "description": "Define si la instancia aparece como en línea o desconectada para los contactos.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "presence": { "description": "Estado de presencia", "type": "string", "enum": [ "available", "unavailable" ] } }, "required": [ "presence" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Presence updated successfully" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/privacy": { "get": { "operationId": "instance_privacy_get", "summary": "Ver privacidad", "description": "Devuelve la configuración de privacidad de la cuenta: quién puede agregarte a grupos, ver la última conexión, la foto de perfil y las confirmaciones de lectura.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "calladd": "all", "groupadd": "all", "last": "contacts", "online": "all", "profile": "all", "readreceipts": "all", "status": "contacts" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "post": { "operationId": "instance_privacy_set", "summary": "Cambiar privacidad", "description": "Actualiza la configuración de privacidad. Todos los campos son opcionales. Envía solo lo que deseas cambiar.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupadd": { "description": "Agregar a grupos", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] }, "last": { "description": "Última conexión", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] }, "profile": { "description": "Foto de perfil", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] }, "readreceipts": { "description": "Confirmación de lectura", "type": "string", "enum": [ "all", "none" ] }, "online": { "description": "Estado en línea", "type": "string", "enum": [ "all", "match_last_seen" ] }, "calladd": { "description": "Recibir llamadas de", "type": "string", "enum": [ "all", "known" ] }, "status": { "description": "Info (texto de estado)", "type": "string", "enum": [ "all", "contacts", "contact_blacklist", "none" ] } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "groupadd": "contacts", "last": "contacts", "profile": "contacts", "readreceipts": "all", "online": "all", "calladd": "all" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/proxy": { "get": { "operationId": "instance_proxy_get", "summary": "Ver proxy", "description": "Devuelve la configuración de proxy de la instancia.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "enabled": true, "managed": true, "proxy_url": "managed_pool://hidden", "proxy_fallback": "internal_proxy", "last_test_at": 1775449088975, "last_test_error": "", "validation_error": false } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "post": { "operationId": "instance_proxy", "summary": "Configurar proxy", "description": "Configura, cambia o ELIMINA el proxy de la instancia. El campo canónico es `mode`: `custom` (proxy propio, exige proxy_url), `internal` (proxy gestionado por el servicio) o `none` (elimina el proxy, exige confirm_no_proxy=true). Para eliminar el proxy, envía mode=none y confirm_no_proxy=true.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "description": "Estrategia de proxy", "type": "string", "enum": [ "custom", "internal", "none" ] }, "proxy_url": { "description": "URL del proxy (obligatorio cuando mode=custom). Protocolos: http://, https://, socks5://", "type": "string", "example": "http://usuario:senha@host:porta" }, "proxy_fallback": { "description": "Contingencia para mode=custom (ej: internal, never)", "type": "string", "example": "internal" }, "confirm_no_proxy": { "description": "Confirma la eliminación del proxy (obligatorio cuando mode=none)", "type": "boolean" }, "rotate_now": { "description": "Cambia el proxy interno de inmediato (cuando mode=internal)", "type": "boolean" } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "details": "Proxy removido", "proxy": { "enabled": false }, "restart_requested": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/reset": { "post": { "operationId": "instance_reset", "summary": "Reiniciar instancia", "description": "Reinicia el runtime de la instancia. Si la instancia está desconectada, será necesario escanear el código QR nuevamente.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "instanceId": "r8ecb82b8e9613c", "resetting": true, "response": "Instance reset started" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/status": { "get": { "operationId": "instance_status", "summary": "Información y estado de la instancia", "description": "Devuelve los datos completos de la instancia: nombre, número de teléfono conectado, foto de perfil y estado actual de la conexión (disconnected, connecting, connected).", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "instance": { "status": "connected", "name": "minha-instancia", "profileName": "Meu Perfil", "owner": "5511999999999", "msg_delay_min": 1, "msg_delay_max": 3 } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/updateDelaySettings": { "post": { "operationId": "instance_updateDelaySettings", "summary": "Configurar delay", "description": "Configura el delay mínimo y máximo entre mensajes en la cola. Devuelve el objeto completo de la instancia.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "msg_delay_min": { "description": "Delay mínimo en segundos (0 = sin delay)", "type": "number", "example": 0 }, "msg_delay_max": { "description": "Delay máximo en segundos", "type": "number", "example": 2 } }, "required": [ "msg_delay_min", "msg_delay_max" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "raa287d88df6336", "name": "minha-instancia", "status": "connected", "msg_delay_min": 0, "msg_delay_max": 2 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/updateInstanceName": { "post": { "operationId": "instance_updateInstanceName", "summary": "Renombrar instancia", "description": "Actualiza el nombre interno de la instancia. Devuelve el objeto completo de la instancia.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Nuevo nombre para la instancia", "type": "string", "example": "Minha Nova Instância 2024!@#" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "raa287d88df6336", "name": "Novo Nome", "status": "connected", "profileName": "Meu Perfil", "owner": "5511999999999" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/label/edit": { "post": { "operationId": "label_edit", "summary": "Crear / Editar etiqueta", "description": "Crea una nueva etiqueta o edita/elimina una existente. Para crear, usa labelid \"0\" con name y color. Para editar, usa el labelid real. Color: número de 0 a 19.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "labelid": { "description": "ID de la etiqueta. Usa \"0\" para crear una nueva.", "type": "string", "example": "0" }, "name": { "description": "Nombre de la etiqueta", "type": "string", "example": "Cliente VIP" }, "color": { "description": "Color (0 a 19)", "type": "number", "example": 5 }, "delete": { "description": "¿Eliminar?", "type": "boolean" } }, "required": [ "labelid", "name" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Label edited successfully" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/labels": { "get": { "operationId": "labels_list", "summary": "Listar etiquetas", "description": "Devuelve todas las etiquetas creadas en la instancia.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "5511999999999:1", "name": "Nao lidas", "color": 0, "colorHex": "#ff9484", "labelid": "1", "owner": "5511999999999" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/labels/refresh": { "post": { "operationId": "labels_refresh", "summary": "Recargar etiquetas", "description": "Recarga las etiquetas de WhatsApp para sincronizarlas con la base de datos local.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "description": "Prueba primero con `false`.\nUsa `true` solo cuando la recarga estándar no funcione bien,\nya que este modo realiza una lectura más completa de las etiquetas.\n", "type": "boolean", "example": false } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "5511999999999:1", "name": "Nao lidas", "color": 0, "labelid": "1" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/quickreply/edit": { "post": { "operationId": "quickreply_edit", "summary": "Crear / Editar respuesta rápida", "description": "Crea o actualiza un atajo de respuesta rápida. Al escribir \"/\" seguido del atajo en WhatsApp, se sugiere el mensaje completo. Para editar, envía el campo `id`.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shortCut": { "description": "Atajo (ej: buen-dia)", "type": "string", "example": "bom-dia" }, "text": { "description": "Texto de la respuesta", "type": "string", "example": "Bom dia! Como posso te ajudar hoje?" }, "type": { "description": "Tipo", "type": "string", "enum": [ "text", "image", "video", "document" ], "default": "text" }, "file": { "description": "URL del archivo (si es multimedia)", "type": "string", "example": "https://..." }, "docName": { "description": "Nombre del documento", "type": "string", "example": "catalogo.pdf" }, "keywords": { "description": "Palabras clave (JSON array)", "type": "string", "example": "[\"bom dia\",\"bom-dia\"]" }, "id": { "description": "ID (para editar)", "type": "string", "example": "qr_abc123" }, "delete": { "description": "Eliminar la respuesta rápida", "type": "boolean" } }, "required": [ "shortCut", "text", "type" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Operation completed successfully", "quickReplies": [ { "id": "r6e84a8016cbd63", "shortCut": "bom-dia", "text": "Bom dia!", "type": "text" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/quickreply/showall": { "get": { "operationId": "quickreply_list", "summary": "Listar respuestas rápidas", "description": "Devuelve todas las respuestas rápidas configuradas en la instancia.", "tags": [ "Configuración" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "id": "r6e84a8016cbd63", "onWhatsApp": false, "docName": "", "file": "", "shortCut": "bom-dia", "text": "Bom dia! Como posso te ajudar?", "type": "text", "owner": "5511999999999" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/sse": { "get": { "operationId": "sse_get", "summary": "Server-Sent Events (SSE)", "description": "Abre una conexión Server-Sent Events para recibir eventos en tiempo real.", "tags": [ "Webhooks y Eventos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": {} } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/webhook": { "get": { "operationId": "webhook_get", "summary": "Ver webhook de la instancia", "description": "Devuelve la configuración de webhooks de la instancia. La respuesta es siempre un array, incluso con un único webhook.", "tags": [ "Webhooks y Eventos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "url": "https://example.com", "enabled": false, "events": [], "id": "r1234" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "post": { "operationId": "webhook", "summary": "Configurar webhook de la instancia", "description": "Gestiona los webhooks de la instancia. Admite modo simple (sin action) y modo multi-webhook (con action: add/update/delete). Para eliminar, envía id + action \"delete\". Los eventos vienen DESACTIVADOS por defecto. Activa solo los que vayas a consumir (evita tráfico innecesario). Los eventos de alto volumen (presence, history) actívalos solo si realmente los vas a procesar.", "tags": [ "Webhooks y Eventos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID único del webhook (necesario para update/delete)", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "enabled": { "description": "Habilita/deshabilita el webhook", "type": "boolean", "example": false }, "url": { "description": "URL para recibir los eventos", "type": "string", "example": "https://example.com/webhook" }, "events": { "description": "Lista de eventos que quieres recibir en tu webhook. TODO viene desactivado por defecto: envía solo los que vayas a usar. Disponibles: connection (conexión), messages (mensajes recibidos/enviados), messages_update (estado: entregado/leído), history (historial al conectar, VOLUMEN ALTO), newsletter_messages (mensajes de canales), call (llamadas), contacts, groups, chats, labels, chat_labels, presence (en línea/escribiendo, VOLUMEN ALTO), blocks (bloqueos), sender. Ejemplo: [\"messages\",\"connection\",\"messages_update\"].", "example": [ "messages", "connection", "messages_update" ] }, "excludeMessages": { "description": "Filtros para excluir tipos de mensajes" }, "addUrlEvents": { "description": "Agrega el tipo de evento como parámetro en la URL.\n- `false` (por defecto): URL normal\n- `true`: agrega el evento a la URL (ej: `/webhook/message`)\n", "type": "boolean" }, "addUrlTypesMessages": { "description": "Agrega el tipo de mensaje como parámetro en la URL.\n- `false` (por defecto): URL normal \n- `true`: agrega el tipo de mensaje (ej: `/webhook/conversation`)\n", "type": "boolean" }, "action": { "description": "Acción a ejecutar:\n- add: crear un nuevo webhook\n- update: actualizar un webhook existente (requiere id)\n- delete: eliminar un webhook (requiere solo id)\nSi no se informa, opera en modo simple (webhook único)\n", "type": "string", "enum": [ "add", "update", "delete" ] } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "Webhook deleted successfully" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/webhook/errors": { "get": { "operationId": "webhook_errors_get", "summary": "Errores del webhook", "description": "Lista los últimos errores de entrega del webhook.", "tags": [ "Webhooks y Eventos" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } }, "example": [ { "created": "2026-04-06T04:00:00Z", "url": "https://...", "event": "messages", "error": "timeout" } ] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/instances/{id}/webhook/deliveries": { "get": { "operationId": "gestao_webhook_deliveries", "summary": "Entregas recientes del webhook", "description": "Lista las últimas entregas de webhook de esta instancia (ventana reciente, para depurar): evento, si fue entregado, estado HTTP, latencia, número de intento y hora. Útil para comprobar si tu endpoint está recibiendo y respondiendo 2xx.", "tags": [ "Webhooks y Eventos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID de la instancia", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Cantidad (máx. 100)", "schema": { "type": "string", "example": "50" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "deliveries": [ { "delivery_id": "uuid", "event": "messages", "event_id": "abc", "ts": 1725600000000, "ok": true, "status": 200, "latency_ms": 142, "attempt": 1 } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/message/async": { "delete": { "operationId": "message_async_delete", "summary": "Limpiar cola async", "description": "Limpia toda la cola de mensajes async.", "tags": [ "Cola Async" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "response": "Async queue cleared", "stats": { "removed": 0, "pending": 0 } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "get": { "operationId": "message_async_get", "summary": "Ver cola async", "description": "Consulta la cola de mensajes async pendientes.", "tags": [ "Cola Async" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "queue": { "status": "idle", "pending": 0, "processingNow": false, "acceptingNewMessages": true }, "response": "Async queue status" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/agent/edit": { "post": { "operationId": "agent_edit", "summary": "Crear/Editar agente de IA", "description": "Crea, edita o elimina un agente de IA para atención automática. Envía id vacío para crear; con valor para editar; delete=true para eliminar.", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del agente", "type": "string", "example": "Vazio para criar novo" }, "delete": { "description": "Eliminar", "type": "boolean", "default": false }, "agent": { "description": "Agente (JSON)", "example": { "name": "Assistente", "provider": "openai", "apikey": "sk-...", "model": "gpt-4o-mini", "basePrompt": "Voce é um assistente...", "maxTokens": 2000, "temperature": 70, "diversityLevel": 50, "frequencyPenalty": 30, "presencePenalty": 30, "signMessages": true, "readMessages": true, "maxMessageLength": 500, "typingDelay_seconds": 3, "contextTimeWindow_hours": 24, "contextMaxMessages": 50, "contextMinMessages": 3 } } }, "required": [ "agent" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "read16c9f35642c", "name": "Assistente", "provider": "openai", "model": "gpt-4o-mini", "apikey": "sk-...", "basePrompt": "Voce e um assistente...", "maxTokens": 500, "temperature": 70, "diversityLevel": 0, "frequencyPenalty": 0, "presencePenalty": 0, "signMessages": false, "readMessages": false, "maxMessageLength": 0, "typingDelay_seconds": 0, "contextTimeWindow_hours": 0, "contextMaxMessages": 0, "contextMinMessages": 0 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/agent/list": { "get": { "operationId": "agent_list_get", "summary": "Listar agentes de IA", "description": "Lista todos los agentes de IA configurados en la instancia. Devuelve un array vacío si no existe ningún agente.", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/function/edit": { "post": { "operationId": "function_edit", "summary": "Crear/Editar función API", "description": "Crea, edita o elimina una función de API para integración con servicios externos. Envía id vacío para crear, con valor para editar, delete=true para eliminar.", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID de la función. Vacío para crear una nueva, con valor para editar una existente.", "type": "string" }, "delete": { "description": "Si es true, elimina la función especificada por el ID.", "type": "boolean" }, "function": { "description": "Configuración de la función (JSON)", "example": { "name": "minha_funcao", "description": "Descricao da funcao", "active": false, "method": "GET", "endpoint": "https://api.example.com/endpoint", "headers": {}, "body": {}, "parameters": [] } } }, "required": [ "id", "delete", "function" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "r72440ced9503e3", "name": "minha_funcao", "description": "Descricao da funcao", "active": false, "method": "GET", "endpoint": "https://api.example.com/endpoint", "headers": "{}", "body": "{}", "parameters": "[]" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/function/list": { "get": { "operationId": "function_list_get", "summary": "Listar funciones API", "description": "Lista todas las funciones de API configuradas. Devuelve un array vacío si no existe ninguna función.", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/knowledge/edit": { "post": { "operationId": "knowledge_edit", "summary": "Crear/Editar conocimiento", "description": "Crea o edita una base de conocimiento para los agentes de IA. (Requiere una API key de OpenAI configurada en la instancia)", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del conocimiento (vacío para crear uno nuevo)", "type": "string" }, "delete": { "description": "Define si es una operación de eliminación", "type": "boolean" }, "knowledge": { "description": "Contenido del conocimiento" }, "fileType": { "description": "Tipo de archivo cuando no se detecta automáticamente", "type": "string", "enum": [ "pdf", "txt", "html", "csv" ] } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/knowledge/list": { "get": { "operationId": "knowledge_list_get", "summary": "Listar conocimientos", "description": "Lista toda la base de conocimiento de los agentes. Devuelve un array vacío si no existe ningún conocimiento.", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/trigger/edit": { "post": { "operationId": "trigger_edit", "summary": "Crear/Editar trigger", "description": "Crea, edita o elimina un trigger de chatbot. Requiere un agente existente (agent_id).", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del trigger", "type": "string", "example": "Vazio para criar novo" }, "delete": { "description": "Eliminar", "type": "boolean", "default": false }, "trigger": { "description": "Trigger (JSON)", "example": { "active": true, "type": "agent", "agent_id": "id_do_agente", "ignoreGroups": true, "priority": 1, "wordsToStart": "ola|oi|iniciar", "responseDelay_seconds": 3, "lead_field": "", "lead_operator": "", "lead_value": "" } } }, "required": [ "trigger" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "rbcca9c181c1e5a", "active": false, "type": "agent", "agent_id": "read16c9f35642c", "flow_id": "", "quickReply_id": "", "ignoreGroups": true, "lead_field": "", "lead_operator": "", "lead_value": "", "priority": 1, "wordsToStart": "ola|oi", "responseDelay_seconds": 3 } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/trigger/list": { "get": { "operationId": "trigger_list_get", "summary": "Listar triggers", "description": "Lista todos los triggers de chatbot configurados. Devuelve un array vacío si no existe ningún trigger.", "tags": [ "Chatbot e IA" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "array", "items": {} }, "example": [] } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chat/editLead": { "post": { "operationId": "chat_editLead", "summary": "Editar lead", "description": "Edita los datos de lead de un contacto. El ID debe incluir @s.whatsapp.net.", "tags": [ "CRM y Leads" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "ID del chat (formato: numero@s.whatsapp.net)", "type": "string", "example": "5511999999999@s.whatsapp.net" }, "lead_name": { "description": "Nombre del lead", "type": "string", "example": "Joao Silva" }, "lead_email": { "description": "Correo electrónico del lead", "type": "string", "example": "joao@email.com" }, "lead_status": { "description": "Estado del lead en el embudo", "type": "string", "example": "qualificado" }, "lead_isTicketOpen": { "description": "Ticket abierto", "type": "boolean" }, "lead_tags": { "description": "Tags (JSON array)", "type": "string", "example": "[\"vip\",\"suporte\"]" }, "lead_notes": { "description": "Notas sobre el lead", "type": "string", "example": "Cliente interessado..." }, "lead_field01": { "description": "Campo personalizado 01", "type": "string" }, "lead_field02": { "description": "Campo personalizado 02", "type": "string" }, "chatbot_disableUntil": { "description": "Desactivar chatbot hasta (timestamp UTC, 0 para reactivar)", "type": "number", "example": 0 }, "lead_personalid": { "description": "Lead Personalid", "type": "string" }, "lead_field03": { "description": "Lead Field03", "type": "string" }, "lead_field04": { "description": "Lead Field04", "type": "string" }, "lead_field05": { "description": "Lead Field05", "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "chat": { "lead_name": "Joao", "lead_email": "joao@email.com" }, "source": "local" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/instance/updateFieldsMap": { "post": { "operationId": "instance_updateFieldsMap", "summary": "Campos personalizados de lead", "description": "Define los nombres de los campos de lead. Los campos son planos (lead_field01, lead_field02, etc).", "tags": [ "CRM y Leads" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_field01": { "description": "Campo 01", "type": "string", "example": "nome" }, "lead_field02": { "description": "Campo 02", "type": "string", "example": "email" }, "lead_field03": { "description": "Campo 03", "type": "string", "example": "telefone" }, "lead_field04": { "description": "Campo 04", "type": "string", "example": "cidade" }, "lead_field05": { "description": "Campo 05", "type": "string", "example": "estado" } } } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "raa287d88df6336", "name": "minha-instancia", "fieldsMap": { "lead_field01": "nome", "lead_field02": "email", "lead_field03": "telefone" } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/chatwoot/config": { "get": { "operationId": "chatwoot_config_get", "summary": "Ver configuración de Chatwoot", "description": "Devuelve la configuración actual de la integración con Chatwoot, incluido el estado de la conexión.", "tags": [ "Integración con Chatwoot" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "chatwoot_enabled": false, "chatwoot_url": "", "chatwoot_account_id": 0, "chatwoot_inbox_id": 0, "chatwoot_inbox_name": "minha-instancia", "chatwoot_access_token": "", "chatwoot_ignore_groups": false, "chatwoot_sign_messages": false, "chatwoot_create_new_conversation": false, "integration_status": { "status": "disabled", "message": "Integracao Chatwoot nao esta habilitada", "connection_ok": false, "credentials_ok": false, "inbox_exists": false } } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } }, "put": { "operationId": "chatwoot_config_put", "summary": "Configurar Chatwoot", "description": "Actualiza la configuración de la integración con Chatwoot. Los campos usan el prefijo chatwoot_. Integración en beta.", "tags": [ "Integración con Chatwoot" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chatwoot_enabled": { "description": "Habilitar integración", "type": "boolean" }, "chatwoot_url": { "description": "URL de Chatwoot (sin barra final)", "type": "string", "example": "https://app.chatwoot.com" }, "chatwoot_access_token": { "description": "Token de acceso de Chatwoot", "type": "string", "example": "pXXGHHHyJPYHYgWHJHYHgJjj" }, "chatwoot_account_id": { "description": "ID de la cuenta en Chatwoot", "type": "number", "example": 1 }, "chatwoot_inbox_id": { "description": "ID de la bandeja de entrada en Chatwoot", "type": "number", "example": 5 }, "chatwoot_ignore_groups": { "description": "Ignorar grupos", "type": "boolean" }, "chatwoot_sign_messages": { "description": "Firmar mensajes", "type": "boolean" }, "chatwoot_create_new_conversation": { "description": "Siempre crear una nueva conversación", "type": "boolean" } }, "required": [ "chatwoot_enabled" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Chatwoot config updated successfully" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/flows": { "get": { "operationId": "flows_list", "summary": "Listar flujos", "description": "Lista todos los flujos del usuario, incluido el estado (habilitado/deshabilitado) y el tipo de gatillo.", "tags": [ "Flujos" ], "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "flows": [ { "id": "abc-123", "name": "Atendimento Delivery", "description": "Fluxo de atendimento automatico", "enabled": true, "trigger": { "type": "keyword", "value": "menu" }, "created_at": "2026-04-10T12:00:00.000Z", "updated_at": "2026-04-15T18:30:00.000Z" } ] } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/flows/{flowId}/trigger": { "post": { "operationId": "flows_trigger", "summary": "Disparar flujo", "description": "Dispara un flujo para un contacto específico. El flujo debe estar habilitado y la instancia conectada. Las variables opcionales quedan disponibles dentro del flujo como {nombre_de_la_variable}. Al llegar a un bloque de webhook, todas las variables recopiladas (respuestas, clics, datos del contacto) se envían a la URL configurada.", "tags": [ "Flujos" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "description": "ID del flujo", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "description": "ID de la instancia", "type": "string", "example": "inst-456" }, "phone": { "description": "Teléfono del contacto", "type": "string", "example": "5511999999999" }, "variables": { "description": "Variables iniciales (objeto JSON)", "example": { "nome": "Joao", "plano": "premium" } } }, "required": [ "instance_id", "phone" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "execution_id": "exec-789", "status": "waiting_reply", "flow_id": "abc-123", "phone": "5511999999999" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } }, "/{instanceId}/tracking/conversion": { "post": { "operationId": "tracking_conversion", "summary": "Registrar venta de un lead de anuncio", "description": "Avisa que un lead que llegó desde un anuncio se convirtió en venta. Es lo que permite a Meta aprender quién realmente compra, en lugar de optimizar solo por quién responde mensajes. Úsalo cuando el pago se confirme en tu sistema. Llamarlo dos veces para la misma venta no la duplica.", "tags": [ "Seguimiento de Meta" ], "parameters": [ { "name": "instanceId", "in": "path", "required": true, "description": "ID de la instancia de WhatsApp (visible en el panel).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "value": { "type": "number" }, "event": { "type": "string" }, "occurred_at": { "type": "string" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "Respuesta exitosa", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "message": "Venda registrada e enviada para a Meta.", "event": "Purchase", "value": 700, "ad_id": "120243748541570695", "lead_status": "won", "status": "queued" } } } }, "400": { "description": "Solicitud inválida (campos ausentes o mal formados)." }, "401": { "description": "Credenciales inválidas (x-api-key / x-api-secret)." }, "429": { "description": "Límite de solicitudes excedido." } } } } } }