# Modificar mensajes WebSocket

> Edita, descarta o envía mensajes WebSocket (WS/WSS) sobre la marcha con onWebsocket en Scripting de Proxyman. Funciona en ambas direcciones, con mensajes de texto y binarios.

## 1. ¿Qué es? {#1-whats-it}

Con la opción **Modify WebSocket Messages**, la función `onWebsocket()` de un script puede cambiar los mensajes WebSocket sobre la marcha. Con unas pocas líneas de JavaScript, puedes:

* Editar un mensaje, por ejemplo, cambiar un campo JSON o reemplazar texto.
* Descartar un mensaje, para que el otro extremo nunca lo vea.
* Enviar un mensaje nuevo al cliente o al servidor.
* Cerrar el WebSocket en ambos extremos.

Funciona con WS y WSS, en ambas direcciones: del cliente al servidor y del servidor al cliente.

> **Nota:** **Modify WebSocket Messages** está disponible en **Proxyman para macOS 26.2.0 o posterior** y en **Proxyman para Windows/Linux 26.1.0 o posterior**. No está disponible en iOS.

<figure class="gb-embed gb-embed--video"><video controls playsinline muted preload="metadata" width="1920" height="1080" src="https://proxyman.com/assets/video/modify-websocket-messages-demo.mp4" aria-label="Una regla de Scripting de Proxyman edita y descarta los mensajes de un WebSocket en vivo"></video><figcaption><p>El servidor envía un precio real de BTC, pero la app recibe $1. Un mensaje con una contraseña se descarta, y la app recibe una advertencia del script.</p></figcaption></figure>

## 2. El problema {#2-the-problem}

Las apps de chat, trading, juegos y paneles en vivo usan WebSocket para recibir datos en tiempo real. Probarlas es difícil:

* **No puedes controlar el servidor.** Envía datos reales. Para que envíe un caso límite, como un precio de 0 o un mensaje de error, habría que cambiar el código del servidor.
* **Algunos casos son difíciles de reproducir.** Un mensaje perdido, una respuesta extraña o una conexión caída rara vez ocurren cuando los necesitas.
* **Otras herramientas no pueden modificar mensajes.** [Breakpoint](https://proxyman.com/docs/es/advanced-features/breakpoint) y [Map Local](https://proxyman.com/docs/es/advanced-features/map-local) actúan sobre el handshake HTTP, no sobre los mensajes que vienen después. Sin esta opción, `onWebsocket()` solo lee los mensajes.

## 3. Beneficios {#3-benefits}

* Prueba todos los mensajes que tu app debe gestionar, sin cambiar el servidor.
* Simula una respuesta del servidor: responde a un mensaje del cliente con `sendToClient()`. El servidor nunca lo recibe.
* Oculta datos sensibles o bloquea eventos de analítica antes de que lleguen al servidor.
* Simula una conexión caída para comprobar cómo se reconecta tu app.
* Solo el WebSocket que coincide con la regla espera al script. El resto del tráfico sigue fluyendo.

## 4. ¿Cómo se usa? {#4-how-to-use-it}

1. Captura tu conexión WebSocket. Para `wss://`, activa [SSL Proxying](https://proxyman.com/docs/es/basic-features/ssl-proxying) para el dominio, como con HTTPS.
2. Haz clic derecho en el flujo `ws://` o `wss://` -> **Tools** -> **Scripting…**. Proxyman crea una regla con la URL rellenada y un script con `onWebsocket()`.
3. Deja marcada la casilla **Request** y marca **Modify WebSocket Messages**.
4. Escribe tu código de `onWebsocket()` y pulsa **Save & Activate** (⌘S, o Ctrl+S en Windows/Linux).
5. Vuelve a conectar el WebSocket. Proxyman lee la opción cuando el WebSocket se conecta, no en cada mensaje.

![El Script Editor de Proxyman con Modify WebSocket Messages marcada y un script de onWebsocket()](https://proxyman.com/docs/assets/script-editor-modify-websocket-messages.jpg)

_Marca Modify WebSocket Messages en el Script Editor_

Este script convierte cada precio de BTC del servidor en $1 y descarta un mensaje del cliente que contiene una contraseña:

```javascript
function onWebsocket(context, url, request, response, message) {
  // Only change text messages. Binary, ping, pong, and close messages pass through
  if (message.type !== "text") {
    return message;
  }

  const json = JSON.parse(message.data);

  // 1. Server -> client: every BTC price becomes $1
  if (message.from === "server" && json.type === "price") {
    json.price = 1;
    json.note = "edited by Proxyman";
    message.data = JSON.stringify(json);
    return message;
  }

  // 2. Client -> server: drop a message with a password, and warn the client
  if (message.from === "client" && json.text.includes("password")) {
    sendToClient(JSON.stringify({ type: "warning", text: "Proxyman blocked a password" }));
    return null;
  }

  // 3. Everything else: send it as it is
  return message;
}
```

La pestaña **Websocket** muestra los mensajes editados, los mensajes enviados por el script y los mensajes descartados:

![La ventana principal de Proxyman con el flujo ws://localhost:3456/prices y sus mensajes WebSocket editados](https://proxyman.com/docs/assets/websocket-tab-edited-messages.jpg)

_Mensajes editados y descartados en la pestaña Websocket_

Para una guía paso a paso con un servidor WebSocket local que puedes ejecutar tú mismo, lee [Cómo modificar mensajes WebSocket con Scripting](https://proxyman.com/posts/2026-10-23-modify-websocket-messages-with-scripting).

## 5. Qué devuelve onWebsocket() {#5-what-onwebsocket-returns}

Cuando la opción está activada, Proxyman retiene cada mensaje de texto y binario hasta que `onWebsocket()` devuelva un resultado. Lo que devuelvas determina qué pasa:

| En `onWebsocket()` | Resultado |
| --- | --- |
| `return message` | Envía el mensaje, con tus cambios. |
| `return null` | Descarta el mensaje. El otro extremo nunca lo recibe. |
| Sin return | Envía el mensaje original. |
| `abort()` | Cierra el WebSocket en ambos extremos. |
| `sendToClient(data)` / `sendToServer(data)` | Envía un mensaje nuevo. Un String envía un mensaje de texto, y un `Uint8Array` envía un mensaje binario. |

El objeto `message` tiene:

| Campo | Valor |
| --- | --- |
| `message.from` | `"client"` o `"server"`. |
| `message.type` | `"text"`, `"binary"`, `"ping"`, `"pong"` o `"close"`. |
| `message.data` | El texto del mensaje. Cámbialo para editar un mensaje de texto. |
| `message.rawData` | Los bytes de un mensaje binario, como `Uint8Array`. Asigna un nuevo `Uint8Array` para editar un mensaje binario. |
| `message.closeCode` | Un número, disponible solo en los mensajes de cierre, como `1000`. |

Consulta [Scripting con WebSocket](https://proxyman.com/docs/es/scripting/script#41-scripting-with-websocket) para ver los demás argumentos.

> **Nota:** La opción viene desactivada por defecto. Cuando está desactivada, `onWebsocket()` funciona como antes: solo lee los mensajes y nunca los retrasa.

## 6. Plantillas {#6-templates}

No hace falta escribir el script desde cero. En el **Script Editor**, haz clic en **Templates** y busca «websocket»:

* **Log WebSocket Messages**: muestra cada mensaje en el Console Log. Solo lee los mensajes.
* **Modify JSON WebSocket Messages**: cambia un campo de los mensajes JSON que envía el servidor.
* **Replace Text in WebSocket Messages**: busca y reemplaza texto en ambas direcciones.
* **Drop WebSocket Messages**: descarta los mensajes que coinciden con una expresión regular, por ejemplo, los eventos de analítica.
* **Reply to a WebSocket Message**: responde a un mensaje del cliente con `sendToClient()`. El servidor nunca lo recibe.
* **Simulate a WebSocket Disconnect**: cierra el WebSocket después de unos cuantos mensajes.

Haz clic en **Replace** para usar una plantilla. Proxyman también marca las casillas que necesita, incluida **Modify WebSocket Messages**.

![La ventana Script Templates de Proxyman, filtrada por las plantillas de WebSocket](https://proxyman.com/docs/assets/websocket-script-templates.jpg)

_Plantillas de WebSocket en el Script Editor_

Hay más ejemplos en la página [Snippet Code](https://proxyman.com/docs/es/scripting/snippet-code#modify-websocket-messages-with-onwebsocket).

## 7. Cosas que conviene saber {#7-good-to-know}

* Puedes editar y descartar mensajes de texto y binarios. Los mensajes ping, pong y close siempre se envían: `onWebsocket()` puede leerlos, pero se ignora lo que devuelve.
* Un mensaje conserva su tipo: no puedes convertir un mensaje de texto en uno binario.
* Si tu script lanza un error o no devuelve un resultado en 30 segundos, Proxyman envía el mensaje original y muestra el error en el Console Log.
* El código fuera de `onWebsocket()` se ejecuta una vez por conexión, así que un contador al inicio del script cuenta los mensajes de cada conexión.
* Los mensajes enviados con `sendToClient()` y `sendToServer()` no vuelven a ejecutar `onWebsocket()`, así que un script que responde no puede entrar en un bucle infinito.
* Cuando varios scripts con esta opción coinciden con el mismo WebSocket, se ejecutan en orden: cada uno recibe lo que devolvió el anterior. Un mensaje descartado no llega a los siguientes scripts.
* Un mensaje de más de 16 MB se envía tal cual, sin pasar por el script.
* Se admiten funciones `async`, así que puedes usar `await` y [$http](https://proxyman.com/docs/es/scripting/async-await-request) en `onWebsocket()`.
* Los agentes de IA pueden crear la misma regla con [Proxyman MCP](https://proxyman.com/docs/es/mcp): `create_scripting_rule` acepta `modify_websocket_messages: true`.

## 8. Solución de problemas {#8-troubleshooting}

### Los mensajes no cambian {#the-messages-dont-change}

* Marca **Modify WebSocket Messages** y, luego, pulsa **Save & Activate** (⌘S, o Ctrl+S en Windows/Linux).
* Vuelve a conectar el WebSocket. La opción se lee cuando el WebSocket se conecta.
* Deja marcada **Request** o **Response**. Una regla con ambas desmarcadas no se ejecuta en absoluto, incluido `onWebsocket()`.
* Devuelve `message` después de cambiarlo. Sin un return, Proxyman envía el mensaje original.
* Abre el Console Log en el Script Editor y busca errores.

### No veo mi WebSocket en Proxyman {#i-cant-see-my-websocket-in-proxyman}

Sigue la guía de [WebSocket](https://proxyman.com/docs/es/advanced-features/websocket) para tu plataforma. Muchas apps y librerías omiten el proxy para `localhost`.