> ## 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. # Conectar instancia a WhatsApp > Inicia la conexión de la instancia con WhatsApp. - Sin `phone`, devuelve un QR Code para escanear con el celular. - Con `phone`, devuelve un código de emparejamiento para ese número. La instancia permanece en `connecting` hasta que se confirme el emparejamiento o expire el plazo. Siga la evolución en `GET /instance/status`; no repita la llamada mientras el proceso esté en curso. Tras la conexión, el historial disponible empieza a llegar mediante el evento `history` y puede consultarse en `POST /message/find` y `POST /chat/find`. La respuesta puede incluir `request_id` en el nivel superior, incluso antes de escanear el QR code o usar el código de emparejamiento. Guarde ese id para correlacionar el intento con los lotes `history` del emparejamiento, incluido el `status` de finalización, y con `GET /instance/history-sync/status`. Permanece igual durante el mismo intento y cambia con cada nuevo emparejamiento. Puede estar ausente cuando no hay emparejamiento ni seguimiento disponible. En un emparejamiento nuevo, `history_days` elige cuántos días de historial envía el celular. Sin el campo, con un valor fuera de 0–365 o de 1 a 90 días, la solicitud es el historial normal (90 días, cuando no hay un valor válido). De 91 a 365 días, o con `0` (el máximo, 365 días), la solicitud es el historial completo, más grande y más lento. Una instancia ya emparejada se reconecta sin solicitar historial. Para elegir una región de conexión, consulte primero `GET /proxy-managed/countries` y `GET /proxy-managed/cities` y reutilice los valores devueltos en los campos `proxy_managed_*`. ## OpenAPI ````yaml /openapi-es.json post /instance/connect 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/connect: post: tags: - Instancia summary: Conectar instancia a WhatsApp description: > Inicia la conexión de la instancia con WhatsApp. - Sin `phone`, devuelve un QR Code para escanear con el celular. - Con `phone`, devuelve un código de emparejamiento para ese número. La instancia permanece en `connecting` hasta que se confirme el emparejamiento o expire el plazo. Siga la evolución en `GET /instance/status`; no repita la llamada mientras el proceso esté en curso. Tras la conexión, el historial disponible empieza a llegar mediante el evento `history` y puede consultarse en `POST /message/find` y `POST /chat/find`. La respuesta puede incluir `request_id` en el nivel superior, incluso antes de escanear el QR code o usar el código de emparejamiento. Guarde ese id para correlacionar el intento con los lotes `history` del emparejamiento, incluido el `status` de finalización, y con `GET /instance/history-sync/status`. Permanece igual durante el mismo intento y cambia con cada nuevo emparejamiento. Puede estar ausente cuando no hay emparejamiento ni seguimiento disponible. En un emparejamiento nuevo, `history_days` elige cuántos días de historial envía el celular. Sin el campo, con un valor fuera de 0–365 o de 1 a 90 días, la solicitud es el historial normal (90 días, cuando no hay un valor válido). De 91 a 365 días, o con `0` (el máximo, 365 días), la solicitud es el historial completo, más grande y más lento. Una instancia ya emparejada se reconecta sin solicitar historial. Para elegir una región de conexión, consulte primero `GET /proxy-managed/countries` y `GET /proxy-managed/cities` y reutilice los valores devueltos en los campos `proxy_managed_*`. requestBody: required: false content: application/json: schema: type: object properties: phone: type: string description: >- Número de teléfono en formato internacional (ej.: 5511999999999). Si se informa, genera un código de emparejamiento. Si se omite, genera un código QR. example: '5511999999999' pattern: ^\d{10,15}$ browser: type: string description: >- Navegador usado en el ciclo de autenticación/conexión. `auto` conserva un perfil válido ya guardado o elige Safari, Firefox o Edge para nuevas conexiones. enum: - auto - safari - firefox - edge - chrome default: auto example: auto systemName: type: string description: >- Sistema/nombre mostrado en el celular en dispositivos vinculados. Ayuda a identificar la instancia en WhatsApp; para mayor estabilidad, recomendamos dejarlo en blanco y usar el valor predeterminado del navegador elegido. example: Mi Empresa proxy_managed_country: type: string description: >- País deseado para el proxy regional, en ISO alpha-2 en minúsculas. Use el valor devuelto por `GET /proxy-managed/countries`. example: br pattern: ^[a-z]{2}$ proxy_managed_state: type: string description: >- Estado/subdivisión de la ciudad elegida. Cuando el país/ciudad requiera desambiguación, use el campo `state` devuelto por `GET /proxy-managed/cities?country=br`. example: sp proxy_managed_city: type: string description: >- Ciudad elegida para el proxy regional. Use siempre el campo `value` devuelto por `GET /proxy-managed/cities`. example: campinas history_days: type: integer minimum: 0 maximum: 365 default: 90 description: > Días de historial solicitados al celular en la vinculación. - Ausente: 90 días, mediante el historial normal. - De `1` a `90`: los últimos N días, mediante el historial normal. - De `91` a `365`: los últimos N días, mediante el historial completo. - `0`: el máximo, 365 días mediante el historial completo. - Fuera de 0–365: se ignora; aplican los 90 días. Solo aplica en una vinculación nueva. Una instancia ya vinculada se reconecta sin solicitar historial, y un código QR o código ya generado mantiene lo que se solicitó. El celular decide qué envía: los días son un límite solicitado, no una garantía. example: 90 examples: qr_code_brasil_com_proxy_regional: summary: Código QR con proxy regional en Campinas/SP value: browser: auto systemName: Minha Empresa proxy_managed_country: br proxy_managed_state: sp proxy_managed_city: campinas codigo_com_um_ano_de_historico: summary: Código de vinculación solicitando 1 año de historial value: phone: '5511999999999' history_days: 365 responses: '200': description: Éxito content: application/json: schema: type: object properties: connected: type: boolean description: Estado actual de la conexión example: false loggedIn: type: boolean description: Estado del inicio de sesión example: false jid: type: - object - 'null' description: ID de WhatsApp (cuando hay sesión iniciada) example: null instance: $ref: '#/components/schemas/Instance' description: Detalles completos de la instancia request_id: type: string description: >- Identificador del intento de emparejamiento y de su historial inicial. Opcional; es el mismo informado en los eventos history y en GET /instance/history-sync/status. example: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f examples: pareamento_em_andamento: summary: Intento de emparejamiento con historial correlacionado value: response: Connecting request_id: 5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f status: connected: false loggedIn: false jid: null '401': description: Token inválido/expirado '404': description: Instancia no encontrada '409': description: Ya existe un flujo de conexión en curso para la instancia '429': description: Límite de conexiones simultáneas alcanzado '500': description: Error interno '503': description: Capacidad de conexión temporalmente no disponible headers: Retry-After: description: Tiempo recomendado, en segundos, para volver a intentarlo. schema: type: integer example: 5 components: schemas: Instance: type: object description: Representa una instancia de WhatsApp properties: id: type: string description: Identificador opaco generado por el servidor. No asuma formato UUID. token: type: string description: Token de autenticación de la instancia status: type: string description: Estado actual de la conexión enum: - disconnected - connecting - connected - hibernated paircode: type: string description: Código de vinculación qrcode: type: string description: Código QR en base64 para autenticación name: type: string description: Nombre de la instancia profileName: type: string description: Nombre del perfil de WhatsApp profilePicUrl: type: string format: uri description: URL de la foto de perfil isBusiness: type: boolean description: Indica si es una cuenta business plataform: type: string description: Plataforma de origen (iOS/Android/Web) systemName: type: string description: Nombre del sistema operativo owner: type: string description: Propietario de la instancia current_presence: type: string description: Estado actual de presencia de la instancia (campo no persistido) enum: - available - unavailable example: available lastDisconnect: type: string description: Fecha/hora textual de la última desconexión lastDisconnectReason: type: string description: Motivo de la última desconexión adminField01: type: string description: Campo administrativo 01 adminField02: type: string description: Campo administrativo 02 openai_apikey: type: string description: Clave de la API de OpenAI chatbot_enabled: type: boolean description: Habilitar chatbot automático chatbot_ignoreGroups: type: boolean description: Ignorar mensajes de grupos chatbot_stopConversation: type: string description: Palabra clave para detener la conversación chatbot_stopMinutes: type: integer description: >- Durante cuánto tiempo permanecerá pausado el chatbot al usar stop conversation chatbot_stopWhenYouSendMsg: type: integer description: >- Durante cuánto tiempo permanecerá pausada la conversación al enviar un mensaje manualmente fieldsMap: type: object description: Mapa de campos personalizados de la instancia (cuando esté presente) additionalProperties: true currentTime: type: string description: Hora actual devuelta por la API created: type: string description: >- Fecha de creación devuelta por la API. Trate el valor como texto; el formato puede variar. updated: type: string description: >- Fecha de la última actualización devuelta por la API. Trate el valor como texto; el formato puede variar. example: id: i91011ijkl token: abc123xyz status: connected paircode: 1234-5678 qrcode: data:image/png;base64,iVBORw0KGg... name: Instância Principal profileName: Loja ABC profilePicUrl: https://example.com/profile.jpg isBusiness: true plataform: Android systemName: WppFy owner: user@example.com lastDisconnect: '2025-01-24T14:00:00Z' lastDisconnectReason: Network error adminField01: custom_data openai_apikey: sk-...xyz chatbot_enabled: true chatbot_ignoreGroups: true chatbot_stopConversation: parar chatbot_stopMinutes: 60 created: '2025-01-24T14:00:00Z' updated: '2025-01-24T14:30:00Z' currentPresence: available securitySchemes: token: name: token type: apiKey in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.