> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # Configurar o cambiar el proxy > Define explícitamente uno de los tres estados aceptados: - `mode=custom`: usa un proxy propio informado en `proxy_url`; - `mode=internal`: usa la infraestructura interna; o - `mode=none`: conexión directa, permitida solo con `confirm_no_proxy=true`. Importante: `POST /instance/proxy` confirma que la configuración fue guardada, no que el proxy ya se haya comprobado en uso. La validación operativa principal ocurre en el próximo ciclo real de conexión de la instancia. En términos prácticos: - `200 OK` aquí = configuración persistida con éxito; - las fallas reales de conectividad pueden aparecer después; y - para observar el estado real, consulte `GET /instance/proxy` y lea: - `effective_mode` - `effective_detail` - `fallback.active` - `last_test_error` - `validation_error` Cuando `mode=custom`, también es posible definir la contingencia mediante `proxy_fallback`: - `internal`: intenta la infraestructura interna y, si aun así falla, puede usar conexión directa como último recurso; - `never`: no usa contingencia; o - una URL de proxy de contingencia controlada por el propio cliente. Cuando `mode=internal`, `rotate_now: true` cambia inmediatamente el proxy interno persistido. Si hay más de un origen interno disponible, la plataforma elige otro origen sin exponer al proveedor. Si hay solo un origen, cambia únicamente el proxy/IP dentro de ese origen. Protocolos aceptados en URLs de proxy personalizado: - `http://usuario:senha@host:porta` - `https://usuario:senha@host:porta` - `socks5://usuario:senha@host:porta` - `socks5h://usuario:senha@host:porta` El esquema genérico `socks://` no se acepta. Para proxies SOCKS, use `socks5://` o `socks5h://`. ## OpenAPI ````yaml /openapi-es.json post /instance/proxy openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para la gestión de instancias de WhatsApp y comunicaciones. ## Recomendación Importante: WhatsApp Business **Se RECOMIENDA ENCARECIDAMENTE usar cuentas de WhatsApp Business** en lugar de WhatsApp normal para la integración; WhatsApp normal puede presentar inconsistencias, desconexiones, limitaciones e inestabilidad durante el uso con nuestra API. ## Autenticación - Los endpoints regulares requieren un header 'token' con el token de la instancia ## Estados de la Instancia Las instancias pueden estar en los siguientes estados: - `disconnected`: Desconectado de WhatsApp - `connecting`: En proceso de conexión - `connected`: Conectado y autenticado con éxito servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Instancia description: > Operaciones relacionadas con el ciclo de vida de una instancia, como conectar, desconectar y verificar el estado. - name: Proxy description: > WppFy opera con un proxy interno por defecto. Puede mantener este valor predeterminado, configurar un proxy propio mediante `proxy_url` o usar su celular Android como proxy instalando la app en https://github.com/WppFy/silver_proxy_apk (APK directo: https://github.com/WppFy/silver_proxy_apk/raw/refs/heads/main/silver_proxy.apk). Si no se envía nada, se sigue usando el proxy interno. Las IPs son brasileñas; para clientes internacionales, considere un proxy de la región del cliente. - name: Perfil description: > Operaciones relacionadas con el perfil de la instancia de WhatsApp, como cambiar el nombre y la imagen de perfil. - name: Business description: > ⚠️ **EXPERIMENTAL** - Endpoints aún no probados por completo. Operaciones relacionadas con el perfil comercial de WhatsApp Business. Permite consultar y actualizar datos del perfil comercial como descripción, dirección, email, categorías y gestionar el catálogo de productos. **Requisitos:** - La cuenta conectada actualmente debe ser una cuenta **WhatsApp Business** - Las cuentas personales de WhatsApp no tienen perfil comercial **Nota:** Estos endpoints pueden no funcionar como se espera. Reporte los problemas encontrados. - name: Llamadas description: | Operaciones relacionadas con llamadas por WhatsApp. Permite realizar y rechazar llamadas de forma programática. - name: Enviar Mensaje description: > Endpoints para el envío de mensajes de WhatsApp con diferentes tipos de contenido. ## Campos Opcionales Comunes Todos los endpoints de envío de mensajes soportan los siguientes campos opcionales: - **`delay`** *(integer)*: Retraso en milisegundos antes del envío - Durante el retraso aparecerá "Escribiendo..." o "Grabando audio..." según el tipo - Ejemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar el chat como leído después del envío - Quita el contador de mensajes no leídos del chat - Ejemplo: `true` - **`readmessages`** *(boolean)*: Marcar los últimos mensajes recibidos como leídos - Marca los últimos 10 mensajes **recibidos** (no enviados por usted) como leídos - Útil para confirmar la lectura de mensajes pendientes antes de responder - A diferencia de `readchat`, que solo quita el contador de no leídos - Ejemplo: `true` - **`replyid`** *(string)*: ID del mensaje a responder - Crea una respuesta vinculada al mensaje original - El soporte varía según el tipo de mensaje - Ejemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números a mencionar (solo para envíos en grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar a todos: `"all"` - **`forward`** *(boolean)*: Marca el mensaje como reenviado en WhatsApp - Agrega el indicador "Reenviado" al mensaje - Ejemplo: `true` - **`track_source`** *(string)*: Origen del rastreo del mensaje - Identifica el sistema o la fuente que está enviando el mensaje - Útil para integraciones (ej.: "chatwoot", "crm", "chatbot") - Ejemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para el rastreo del mensaje - Identificador libre para dar seguimiento al mensaje en sistemas externos - Permite correlacionar mensajes entre diferentes plataformas - **Nota**: El sistema acepta valores duplicados; no hay validación de unicidad - Use el mismo ID en varios mensajes si tiene sentido para su integración - Ejemplo: `"msg_123456789"` ### Envío a Grupos - **`number`** *(string)*: Para enviar un mensaje a un grupo, use el ID del grupo que termina en `@g.us` - Ejemplo: `"120363012345678901@g.us"` - **Cómo obtener el ID del grupo:** - Use el `chatid` del webhook recibido cuando alguien envía un mensaje en el grupo - Use el endpoint `GET /group/list` para listar todos los grupos y sus IDs ## Placeholders Disponibles Todos los endpoints de envío de mensajes soportan placeholders dinámicos para personalización automática: ### Campos de Nombre - **`{{name}}`**: Nombre consolidado del chat, usando la primera opción disponible: 1. Nombre del lead (`lead_name`) 2. Nombre completo del lead (`lead_fullName`) 3. Nombre del contacto en WhatsApp (`wa_contactName`) 4. Nombre del perfil de WhatsApp (`wa_name`) - **`{{first_name}}`**: Primera palabra válida del nombre consolidado (mínimo 2 caracteres) ### Campos de WhatsApp - **`{{wa_name}}`**: Nombre del perfil de WhatsApp - **`{{wa_contactName}}`**: Nombre del contacto tal como está guardado en WhatsApp ### Campos del Lead - **`{{lead_name}}`**: Nombre del lead - **`{{lead_fullName}}`**: Nombre completo del lead - **`{{lead_personalid}}`**: ID personal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email del lead - **`{{lead_status}}`**: Estado actual del lead - **`{{lead_notes}}`**: Anotaciones del lead - **`{{lead_assignedAttendant_id}}`**: ID del agente asignado ### Campos Personalizados Los campos agregados mediante custom fields son accesibles usando `{{lead_field01}}` a `{{lead_field20}}` o usando `{{nomedocampo}}` definido en `/instance/updateFieldsMap`. ### Ejemplo de Uso ``` ¡Hola {{name}}! Vi que usted trabaja en {{company}}. ¿Su email {{lead_email}} es correcto? ``` **💡 Consejo**: Use `/chat/find` para buscar los datos del chat y ver los campos disponibles antes de enviar mensajes con placeholders. - name: Mensaje Async description: > Controles operativos de la cola interna de envío asíncrono usada cuando un endpoint de envío recibe `async=true`. Esta sección sirve para: - consultar el estado actual de la cola async - configurar el delay entre mensajes enviados con `async=true` - limpiar el backlog pendiente y cancelar mensajes aún no concluidos Alcance: - cubre solo la cola interna de mensajes directos async - no modifica mensajes ya enviados correctamente - name: Acciones en el mensaje y Búsqueda - name: Chats - name: Contactos - name: Bloqueos - name: Etiquetas - name: Grupos y Comunidades - name: Newsletters y Canales description: > Operaciones para la lectura y el seguimiento de canales de WhatsApp (newsletters). Casos de uso principales: - listar posts ya publicados en un canal - editar posts recientes de un canal - eliminar posts recientes de un canal - consultar views y reacciones de los posts - integrar canales sin necesidad de persistir los mensajes localmente Observaciones: - `/newsletter/messages` devuelve el contenido de los posts - `/newsletter/messages/edit` edita el contenido de posts recientes - `/newsletter/messages/delete` elimina posts recientes - las views (`viewsCount`) y reactions (`reactionCounts`) vienen en cada post de `/newsletter/messages`, no por evento de webhook - `/newsletter/updates` está obsoleta: WhatsApp no responde y la API devuelve 504 - los newsletters usan rutas propias y no deben usar `/message/edit` ni `/message/delete` - name: Respuestas Rápidas description: > Gestión de respuestas rápidas para agilizar la atención. **⚠️ Importante**: Este recurso solo es útil si utiliza un sistema frontend/interfaz personalizada para registrar y utilizar las respuestas. La API solo almacena las respuestas, pero no las aplica automáticamente. ### Cómo funciona: - **Crear**: Registre respuestas predefinidas con títulos y contenido - **Listar**: Recupere todas las respuestas registradas para mostrarlas en su interfaz - **Usar**: Su sistema frontend puede usar estas respuestas para agilizar la escritura ### Casos de uso: - Interfaces web personalizadas de atención - Apps móviles con sugerencias de respuesta - Sistemas CRM con plantillas de mensaje - Herramientas de productividad para agentes **No es un chatbot**: Para respuestas automáticas, use los recursos de Chatbot. - name: CRM description: > Sistema completo de gestión de relaciones con clientes integrado a la API. **💾 Almacenamiento interno**: Todos los datos de los leads se guardan directamente en la API, eliminando la necesidad de bases de datos externas. Su aplicación puede enfocarse solo en la interfaz y la lógica de negocio. ### Recursos disponibles: - **📋 20+ campos personalizables**: Nombre, teléfono, email, empresa, observaciones, etc. - **🏷️ Sistema de etiquetas**: Organice y categorice sus contactos - **🔍 Búsqueda avanzada**: Filtre por cualquier campo o etiqueta - **📊 Historial completo**: Todas las interacciones se registran automáticamente ### 🎯 Placeholders en mensajes: Use variables dinámicas en los mensajes para la personalización automática: ``` ¡Hola {{nombre}}! Vi que trabaja en {{empresa}}. ¿Su email {{email}} es correcto? Observaciones: {{observaciones}} ``` ### Flujo típico: 1. **Captura**: Los leads llegan vía WhatsApp o formularios 2. **Enriquecimiento**: Agregue datos usando `/chat/editLead` 3. **Segmentación**: Organice con etiquetas 4. **Comunicación**: Envíe mensajes personalizados con placeholders 5. **Seguimiento**: El historial se guarda automáticamente **Ideal para**: Ventas, marketing, atención, calificación de leads - name: Integración con Chatwoot description: > **🚧 INTEGRACIÓN BETA - Sistema de integración con Chatwoot para atención unificada** **⚠️ AVISO**: Esta integración está en fase BETA. Úsela bajo su propio riesgo. Recomendamos realizar pruebas en un entorno no productivo antes de usarla en producción. Esta categoría contiene recursos para configurar y gestionar la integración con Chatwoot, una plataforma de atención al cliente open-source. La integración permite centralizar las conversaciones de WhatsApp en Chatwoot. ### Recursos disponibles: - 🔧 **Configuración Completa**: Configure URL, tokens y credenciales de Chatwoot - 📬 **Sincronización Bidireccional**: Los mensajes nuevos entre WhatsApp y Chatwoot se sincronizan automáticamente - 📱 **Gestión de Contactos**: Sincronización automática de nombres y teléfonos - 🔄 **Actualización LID→PN**: Migración automática de Local ID a Phone Number - 🏷️ **Nombres Inteligentes**: Sistema de nombres con tilde (~) para actualización automática - 🚫 **Separación de Grupos**: Opción para ignorar grupos en la sincronización - 👤 **Firma de Mensajes**: Identificación del agente en los mensajes enviados - 🔗 **Webhook Automático**: URL generada automáticamente para configurar en Chatwoot ### 🏷️ Sistema de Nombres Inteligentes: - **Nombres con tilde (~)**: Se actualizan automáticamente cuando el contacto modifica su nombre en WhatsApp - **Nombres específicos**: Para un nombre fijo, quite la tilde (~) del nombre en Chatwoot - **Ejemplo**: "~Juan Pérez" = automático, "Juan Pérez" = fijo - **Migración LID→PN**: Sin duplicación de conversaciones durante la transición - **Respuestas nativas**: Aparecen directamente en Chatwoot sin marcas externas ### ⚠️ Limitaciones conocidas: - **Sincronización del historial**: No implementada - solo se sincronizan los mensajes nuevos ### Casos de uso: - Atención centralizada en Chatwoot - Equipos de soporte con múltiples agentes - Integración con CRM mediante Chatwoot - Centralización de canales de comunicación - Gestión automática de contactos y nombres **Ideal para**: Empresas con equipos de atención, call centers, soporte técnico (en entorno de pruebas) **Requiere**: Instancia de Chatwoot configurada, tokens de API y entorno de pruebas **🚧 Recuerde**: Integración en BETA - las funcionalidades pueden cambiar sin previo aviso - name: Server-Sent Events (SSE) paths: /instance/proxy: post: tags: - Proxy summary: Configurar o cambiar el proxy description: > Define explícitamente uno de los tres estados aceptados: - `mode=custom`: usa un proxy propio informado en `proxy_url`; - `mode=internal`: usa la infraestructura interna; o - `mode=none`: conexión directa, permitida solo con `confirm_no_proxy=true`. Importante: `POST /instance/proxy` confirma que la configuración fue guardada, no que el proxy ya se haya comprobado en uso. La validación operativa principal ocurre en el próximo ciclo real de conexión de la instancia. En términos prácticos: - `200 OK` aquí = configuración persistida con éxito; - las fallas reales de conectividad pueden aparecer después; y - para observar el estado real, consulte `GET /instance/proxy` y lea: - `effective_mode` - `effective_detail` - `fallback.active` - `last_test_error` - `validation_error` Cuando `mode=custom`, también es posible definir la contingencia mediante `proxy_fallback`: - `internal`: intenta la infraestructura interna y, si aun así falla, puede usar conexión directa como último recurso; - `never`: no usa contingencia; o - una URL de proxy de contingencia controlada por el propio cliente. Cuando `mode=internal`, `rotate_now: true` cambia inmediatamente el proxy interno persistido. Si hay más de un origen interno disponible, la plataforma elige otro origen sin exponer al proveedor. Si hay solo un origen, cambia únicamente el proxy/IP dentro de ese origen. Protocolos aceptados en URLs de proxy personalizado: - `http://usuario:senha@host:porta` - `https://usuario:senha@host:porta` - `socks5://usuario:senha@host:porta` - `socks5h://usuario:senha@host:porta` El esquema genérico `socks://` no se acepta. Para proxies SOCKS, use `socks5://` o `socks5h://`. requestBody: required: true content: application/json: examples: custom_with_internal_fallback: summary: Proxy personalizado con fallback interno value: mode: custom proxy_url: http://usuario:senha@proxy-do-cliente.example:8080 proxy_fallback: internal custom_with_explicit_backup_proxy: summary: Proxy personalizado con proxy de contingencia propio value: mode: custom proxy_url: http://usuario:senha@proxy-principal.example:8080 proxy_fallback: socks5://backup:senha@proxy-backup.example:1080 internal_now: summary: Modo interno value: mode: internal internal_rotate_now: summary: Rotar proxy interno ahora value: mode: internal rotate_now: true no_proxy: summary: Directo explícito value: mode: none confirm_no_proxy: true schema: type: object properties: mode: type: string enum: - custom - internal - none description: Campo canónico para definir la estrategia de proxy. proxy_url: type: string description: > Obligatorio cuando `mode=custom`. Protocolos aceptados: `http://`, `https://`, `socks5://` y `socks5h://`. El esquema genérico `socks://` no es compatible; use `socks5://` o `socks5h://`. example: http://usuario:senha@ip:porta proxy_fallback: type: string description: > Política de contingencia para `mode=custom`. Acepta `internal`, `never` o una URL de proxy de contingencia usando `http://`, `https://`, `socks5://` o `socks5h://`. confirm_no_proxy: type: boolean description: Obligatorio cuando `mode=none`. rotate_now: type: boolean description: >- Cuando es `true` con `mode=internal`, cambia de inmediato el proxy interno persistido sin exponer el proveedor utilizado. default: false proxy_managed_country: type: string description: >- País ISO alpha-2 utilizado para validar la salida del proxy gestionado. Úselo solo con `mode=internal`. example: br proxy_managed_state: type: string description: >- Estado/provincia del objetivo geográfico devuelto por el catálogo de ciudades. example: sp proxy_managed_city: type: string description: Slug de la ciudad devuelto por `GET /proxy-managed/cities`. example: campinas responses: '200': description: Proxy configurado con éxito content: application/json: examples: custom_internal_fallback_saved: summary: >- Configuración guardada; el uso real se confirmará en el próximo ciclo de conexión value: details: Proxy configurado proxy: mode: custom effective_mode: custom fallback: active: false reason: '' since: 0 proxy_url: http://***:***@proxy-do-cliente.example:8080 proxy_fallback: internal managed: false last_test_at: 0 last_test_error: '' validation_error: false restart_requested: true after_connect_failure_example: summary: >- Ejemplo de lo que GET puede mostrar después si el proxy guardado falla value: details: Proxy configurado proxy: mode: custom effective_mode: custom fallback: active: false reason: '' since: 0 proxy_url: http://***:***@proxy-do-cliente.example:8080 proxy_fallback: internal managed: false last_test_at: 0 last_test_error: '' validation_error: false restart_requested: true direct_explicit: summary: Directo explícito value: details: Proxy configurado proxy: mode: none effective_mode: direct fallback: active: false reason: '' since: 0 proxy_url: '' proxy_fallback: internal managed: false last_test_at: 0 last_test_error: '' validation_error: false internal_rotated: summary: Proxy interno rotado value: details: Proxy configurado rotated: true proxy: mode: internal effective_mode: internal effective_detail: managed_pool fallback: active: false reason: '' since: 0 proxy_url: managed_pool://hidden proxy_fallback: internal managed: true last_test_at: 0 last_test_error: '' validation_error: false schema: type: object example: details: Proxy configurado proxy: mode: custom effective_mode: custom fallback: active: false reason: '' since: 0 proxy_url: http://***:***@proxy-do-cliente.example:8080 proxy_fallback: internal managed: false last_test_at: 0 last_test_error: '' validation_error: false restart_requested: true properties: details: type: string example: Proxy configurado proxy: type: object properties: mode: type: string enum: - custom - internal - none description: Intención persistida del cliente después del guardado. effective_mode: type: string enum: - custom - internal - direct description: Transporte efectivo en el momento de la respuesta. effective_detail: type: string enum: - managed_pool - internal_route - relay description: >- Detalle complementario del transporte efectivo. Cuando no hay detalle adicional, el campo se omite. fallback: type: object description: Estado actual de la contingencia. properties: active: type: boolean description: >- Indica si la instancia está operando en fallback en este momento. reason: type: string description: Motivo interno resumido del fallback actual. since: type: integer description: >- Timestamp Unix en milisegundos desde que el fallback actual está activo. proxy_url: type: string description: URL enmascarada del proxy persistido. proxy_fallback: type: string description: >- Política de contingencia persistida para `mode=custom`. managed: type: boolean description: >- Campo heredado vinculado al uso de la infraestructura interna. last_test_at: type: integer description: Timestamp de la última prueba/error persistido. last_test_error: type: string description: Último error persistido para diagnóstico. validation_error: type: boolean description: Indica si `last_test_error` está completado. restart_requested: type: boolean description: >- Indica si se solicitó un reinicio de la conexión para aplicar el proxy. rotated: type: boolean description: >- Presente como `true` cuando `rotate_now` cambia el proxy interno con éxito. '400': description: Payload inválido o falla en la validación del proxy content: application/json: schema: type: object properties: error: type: string example: confirm_no_proxy es obligatorio para deshabilitar el proxy '401': description: Token inválido o expirado content: application/json: schema: type: object properties: error: type: string example: Unauthorized '409': description: No hay un proxy alternativo disponible para la rotación interna content: application/json: schema: type: object properties: error: type: string example: >- no fue posible rotar el proxy interno: no hay ningún proxy alternativo disponible para la rotación '500': description: Error interno del servidor al configurar el proxy content: application/json: schema: type: object properties: error: type: string description: Mensaje que detalla el error encontrado security: - token: [] components: securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.