fn_registry/python/functions/browser/whatsapp_send_image.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params_schema, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params_schema	tested	tests	test_file_path	file_path
whatsapp_send_image	function	py	browser	1.0.0	impure	def whatsapp_send_image(name: str, image_path: str, *, caption: str = '', port: int = 9222, target_url_substr: str = 'whatsapp', open_first: bool = True) -> dict	Envia una imagen (con caption opcional) a un chat de WhatsApp Web en una pestana ya logueada del navegador diario via CDP, sin abrir ventana nueva ni darle foco. Abre el chat por nombre exacto (whatsapp_open_chat) y verifica el destinatario (salvaguarda anti-envio-equivocado), hace click real en 'Adjuntar' para exponer el <input type=file> vivo, asigna la imagen con cdp_set_file_input (DOM.setFileInputFiles), espera la bandeja inline y hace click en el boton enviar (icono wds-ic-send-filled) verificando que la bandeja se cerro. Si hay caption, lo envia como mensaje de texto de seguimiento via whatsapp_send_message (en la WhatsApp Web compacta actual el caption embebido en la imagen no es automatizable de forma fiable, asi que viaja como segunda burbuja [imagen][caption]). Accion con efecto: envia la imagen DE VERDAD, no reversible.	whatsapp cdp browser automation image upload python navegator	whatsapp_open_chat_py_browser cdp_eval_py_browser cdp_click_xy_py_browser cdp_set_file_input_py_browser whatsapp_send_message_py_browser			false	error_go_core	os sys time json	params output name desc name Nombre EXACTO del chat o grupo destinatario tal y como aparece en la lista lateral. Se usa para abrir el chat y como salvaguarda de que el composer apunta al destinatario correcto antes de adjuntar. name desc image_path Ruta de la imagen a enviar. Se expande (~) y se convierte a ruta ABSOLUTA; debe existir en disco o aborta con error sin abrir el chat. name desc caption Texto opcional descriptivo. Se envia como un MENSAJE DE TEXTO de seguimiento (segunda burbuja [imagen][caption]) via whatsapp_send_message; '' (default) envia solo la imagen. La WhatsApp Web compacta actual no permite automatizar el caption embebido en la imagen de forma fiable. name desc port Puerto de remote debugging de Chrome. Default 9222. name desc target_url_substr Substring que debe contener la URL del target (pestana). Default 'whatsapp'. name desc open_first Si True (default), abre el chat por su nombre antes de adjuntar. Si False, asume el chat ya abierto pero verifica el aria-label del composer contra name (aborta si no coincide). dict {ok: bool (imagen + caption enviados), sent: bool (imagen enviada), caption_sent: bool (caption de seguimiento enviado, False si no habia o fallo), recipient: str, image: str (ruta absoluta), caption: str, error: str (motivo del fallo, vacio si todo ok)}. sent=True solo si la imagen se adjunto y se envio dejando la bandeja vacia. Nunca lanza: los fallos se reportan en 'sent'/'ok' + 'error'.	true	test_golden_envia_imagen_y_caption_de_seguimiento test_envia_sin_caption_no_manda_texto test_edge_imagen_no_existe_error_sin_abrir test_edge_open_fallido_error_sin_adjuntar test_seguridad_open_first_false_label_no_coincide_aborta test_error_set_file_input_falla_no_envia	python/functions/browser/whatsapp_send_image_test.py	python/functions/browser/whatsapp_send_image.py

Ejemplo

import sys, os
sys.path.insert(0, os.path.join("python", "functions"))
from browser.whatsapp_send_image import whatsapp_send_image

# Requiere WhatsApp Web abierto y logueado (y DESBLOQUEADO si tiene app-lock) en un
# Chrome lanzado con --remote-debugging-port=9222.
res = whatsapp_send_image(
    "NOTAS WASAP",
    "/home/enmanuel/ComfyUI/output/item_icon_potion_00001_.png",
    caption="item icon: potion",
)
print(res)
# -> {"ok": True, "sent": True, "recipient": "NOTAS WASAP",
#     "image": ".../item_icon_potion_00001_.png", "caption": "item icon: potion", "error": ""}

O directo por CLI: python3 python/functions/browser/whatsapp_send_image.py "NOTAS WASAP" /ruta/abs.png "mi caption".

Cuando usarla

Cuando necesites enviar una imagen (foto, captura, asset generado) a un contacto o grupo por su nombre exacto en WhatsApp Web, sin abrir ventana nueva ni robar el foco al usuario. Es la version "imagen" de whatsapp_send_message_py_browser: usala cuando ya tienes el nombre exacto del destinatario y la ruta de un archivo de imagen en disco. Para texto plano, usa whatsapp_send_message; para leer/confirmar lo enviado, whatsapp_read_chat.

Gotchas

• Accion con efecto: envia la imagen DE VERDAD. No es reversible. Verifica que name es EXACTO antes de llamar (la salvaguarda abre el chat y comprueba el composer, pero el nombre debe coincidir con el title de la lista lateral).
• App-lock de WhatsApp Web. Si la cuenta tiene el "bloqueo de la aplicacion" activo, el DOM de chats no se renderiza (solo la pantalla de password) y la funcion fallara al abrir el chat. Hay que desbloquearlo primero (teclear el password en input[type=password] + boton "Desbloquear"). Sintoma: whatsapp_open_chat devuelve opened: False y la lista lateral sale vacia aunque la sesion siga logueada.
• El input vivo solo existe tras pulsar "Adjuntar". Por eso la funcion hace el click real en el boton "Adjuntar" antes de setFileInputFiles; asignar al input persistente decoy no abre el preview. La WhatsApp Web actual usa una bandeja de medios INLINE compacta sobre el composer (no un drawer a pantalla completa).
• El caption NO se embebe en la imagen: viaja como mensaje de texto de seguimiento. En esta WhatsApp Web compacta hay dos botones de envio cuando hay media: "Enviar N seleccionados" (envia la bandeja, IGNORA el texto del composer) y "Enviar"/Enter (envia el texto como burbuja aparte, descartando la media en cola). No hay un campo de caption por-imagen automatizable de forma fiable. Por eso la funcion envia primero la imagen (boton de la bandeja) y, si hay caption, lo manda despues como mensaje de texto via whatsapp_send_message (open_first=False): el resultado es [imagen][caption] como dos burbujas. caption_sent indica si esa segunda burbuja salio.
• Selector de aria-label en espanol. El preview se detecta por [aria-label="Quitar archivo adjunto"] y el boton de adjuntar por [aria-label="Adjuntar"]: dependen del idioma de la UI (espanol). En otro locale habria que ajustar los aria-labels.
• Las imagenes se ACUMULAN en la bandeja. Cada setFileInputFiles anade una miniatura; si un envio queda a medias, la siguiente llamada podria sumar a las pendientes. La funcion verifica que la bandeja queda vacia tras enviar (adjuntos=0) para confirmar; si no se cierra, devuelve sent=False con "envio incierto".
• Salvaguarda anti-destinatario-equivocado: con open_first=True abre y verifica el chat; con open_first=False lee el aria-label del composer y aborta si no contiene name.
• Funciona con la ventana minimizada o sin foco: CDP opera la pestana sin traerla a primer plano.
• Viola los ToS de WhatsApp: automatizar la web tiene riesgo de ban del numero personal. Usar con cautela y bajo tu responsabilidad.