# Encuestas en WhatsApp y en tu app (/es/guides/native-surveys) Abrir un mensaje no responde una encuesta. Bitelio mantiene una invitación y un borrador compartidos entre el navegador, WhatsApp y tu app móvil. Cada respuesta se valida frente a las preguntas publicadas que siguen disponibles. Para configurar primero las encuestas y los canales desde el panel, consulta [Encuestas que se adaptan](/es/second-purchase/surveys) y [Canales y atención al cliente](/es/second-purchase/channels). Esta guía describe la integración técnica; habilitar un canal no sustituye su conexión ni el consentimiento del cliente. ## WhatsApp Conecta el número propio del comercio en **Segunda compra → Configuración → Canales**. El cliente debe tener permiso vigente de WhatsApp. Selecciona una plantilla de marketing aprobada para cada idioma, con texto fijo y este botón de enlace: ```text https://app.bitelio.com/surveys/respond#token={{1}} ``` Para responder dentro de WhatsApp, añade un botón de respuesta rápida aprobado con el texto **Responder aquí**, **Responder encuesta** o **Comenzar encuesta**. También se admiten **Answer here**, **Answer survey** y **Start survey**. Conserva el enlace para que el cliente pueda continuar en el navegador. Actualiza las plantillas cuando Meta apruebe el cambio. La configuración indica si cada plantilla permite responder dentro de WhatsApp o mediante enlace. Al pulsarlo, el cliente recibe la siguiente pregunta visible. Las preguntas de opción única usan botones o una lista. Cada respuesta guarda el progreso. La confirmación final **Enviar respuestas** completa la encuesta y aplica sus conclusiones. La ayuda y las recomendaciones posteriores se consultan en el enlace de la misma encuesta. | Capacidad | Comportamiento en WhatsApp | | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | | Opción única y condiciones entre preguntas | Respuesta dentro de WhatsApp; la siguiente pregunta depende de las anteriores | | Hasta 10 opciones, incluyendo Omitir si procede | Botones o lista, con etiquetas completas de hasta 72 caracteres | | Valoraciones | Disponibles si el número de opciones cabe en la lista | | Opción múltiple, etiquetas largas o más opciones | Continúa en el enlace conservando el progreso | | Idioma de la conversación nativa | Español e inglés; otros idiomas continúan en su encuesta del navegador | | Texto libre, audio e imágenes | No se interpretan como respuestas; mantienen el tratamiento de ayuda existente | | Ventana de atención | Respuestas nativas durante las 24 horas siguientes a una respuesta verificada del cliente | Fuera de esa ventana no se envían mensajes de sesión sin aprobación. El enlace original sigue disponible. Pulsar de nuevo el botón original puede abrir otra conversación nativa mientras la invitación siga vigente. Si se cambia una respuesta desde el navegador, los botones antiguos dejan de ser válidos; vuelve a abrir la invitación para continuar con el borrador actual. Bitelio comprueba la firma de Meta y vincula cada opción al comercio, teléfono, invitación, mensaje concreto, pregunta, opción, versión del borrador y caducidad. Los reintentos del webhook no duplican respuestas ni mensajes ya aceptados. Un envío cuya aceptación sea incierta no se reenvía automáticamente. Cada turno nativo es otro envío del proveedor. No se presume gratuito: los intentos sin evidencia de coste permanecen como coste desconocido hasta su conciliación. Importa cada línea acreditada de la factura con `POST /v1/retention/messages/cost-receipts`, indicando `turnId` o el `providerMessageId` exacto del turno nativo. `deliveryId` identifica solo la invitación inicial. Contratos del proveedor: [botones de Meta](https://www.postman.com/meta/whatsapp-business-platform/request/x0kd1at/send-reply-button) y [respuestas rápidas en plantillas de Meta](https://www.postman.com/meta/whatsapp-business-platform/request/lwtlz1k/send-message-template-interactive). ## Integración nativa en una app móvil Tu servidor entrega las notificaciones mediante tu integración con APNs o FCM. Bitelio no recibe las credenciales de notificaciones del dispositivo. Habilita Mobile API, registra el permiso del cliente con `POST /v1/retention/mobile-permissions`, recoge una invitación y confirma su aceptación o entrega real. Una invitación todavía no aceptada por el canal no permite crear una sesión nativa. ### 1. Crea la sesión desde tu servidor Autentica primero al cliente en tu app. Tu servidor debe determinar su contacto de Bitelio y un identificador opaco del dispositivo; no aceptes un contacto arbitrario enviado por la app. Conserva en el servidor la clave secreta y el token de recibo de la entrega. ```http POST /v1/retention/mobile-survey-sessions Authorization: Bearer sk_TU_CLAVE_SECRETA Content-Type: application/json { "deliveryId": "UUID_DE_ENTREGA", "contactId": "ID_DEL_CONTACTO", "receiptToken": "UUID_DEL_RECIBO_EN_SERVIDOR", "deviceId": "identificador-dispositivo" } ``` La clave necesita `retention:view` y `retention:edit`. El dispositivo admite 16–128 letras, números, `_` o `-`; no utilices el correo ni el teléfono. La respuesta contiene `sessionToken`, `expiresAt` y las capacidades disponibles. Dura como máximo 15 minutos y queda vinculada al dispositivo, entrega y cliente. Los cambios en el permiso la invalidan. La vinculación se apoya en la autenticación de tu servidor; no constituye una certificación del hardware. Entrega a la app únicamente la sesión, su caducidad y el identificador del dispositivo a través de tu conexión autenticada. Guárdalos en almacenamiento protegido, nunca en notificaciones, analítica ni URLs. Renueva la sesión desde el servidor al caducar. ### 2. Muestra la encuesta real ```http GET /public/retention/mobile-survey X-Bitelio-Mobile-Session: TOKEN_DE_SESION X-Bitelio-Device: identificador-dispositivo ``` La respuesta usa `BuyerSurveyView`: estado, identidad de marca, idioma, preguntas y borrador `draft`. Solo se responden encuestas `OPEN`. Recorre las preguntas en su orden y aplica cada condición `showWhen` a las respuestas anteriores visibles. Nunca muestres ni envíes una rama oculta. Utiliza controles de opción única, múltiple o valoración, sin sustituirlos por texto libre. Recupera `answers` y `throughQuestionId` al reanudar. Tras completar pueden aparecer `completion`, `help` y `nextStep`; conserva sus opciones y acciones reales. ### 3. Guarda cada paso confirmado Al pulsar Continuar, envía todo el tramo visible confirmado, incluidas las respuestas anteriores: ```http POST /public/retention/mobile-survey/progress X-Bitelio-Mobile-Session: TOKEN_DE_SESION X-Bitelio-Device: identificador-dispositivo Content-Type: application/json { "revision": 0, "throughQuestionId": "recipient", "answers": [{"questionId": "recipient", "value": "self"}] } ``` Usa los identificadores y valores devueltos por la API. Las respuestas múltiples son arrays de valores y las valoraciones son números. Guardar no completa la encuesta ni publica conclusiones del cliente. Conserva la revisión devuelta. Si cambia una respuesta anterior, elimina las respuestas de las ramas ocultas y de los pasos posteriores aún no confirmados. ### 4. Envía tras la confirmación final ```http POST /public/retention/mobile-survey/submit X-Bitelio-Mobile-Session: TOKEN_DE_SESION X-Bitelio-Device: identificador-dispositivo Content-Type: application/json {"revision": 1, "answers": [{"questionId": "recipient", "value": "self"}]} ``` Incluye todas las respuestas visibles obligatorias. Los reintentos idénticos son idempotentes. Ante `409 SURVEY_DRAFT_CONFLICT`, recarga y deja que el cliente revise los cambios hechos en otro dispositivo; no sobrescribas automáticamente. Un `404` indica que la sesión o el permiso no están disponibles: vuelve a tu servidor autenticado. Las respuestas son privadas y no deben cachearse. El límite público es de 60 peticiones por sesión y minuto; `429` devuelve `Retry-After`. ## Comprar de nuevo o pedir ayuda sin responder antes Con las mismas dos cabeceras de sesión, `GET /public/retention/mobile-survey/actions` devuelve las acciones disponibles y no registra interacción. Muéstralas junto a la encuesta para que un cliente dispuesto a comprar no tenga que completarla primero. `POST /public/retention/mobile-survey/actions` acepta, por ejemplo, `{"action":"REPEAT","stage":"REQUESTED"}` o `{"action":"DISCOVER","stage":"REQUESTED"}` y devuelve hasta tres productos actuales. Muestra sus imágenes, variantes y motivos reales. Registra `VIEWED` solo tras una interacción deliberada. `SELECTED` y `CHECKOUT` requieren el `productId` y `variantId` exactos de una opción devuelta. Para comprar, utiliza la `url` que devuelve Bitelio tras comprobar de nuevo existencias y condiciones. No construyas un carrito a partir de una sugerencia antigua. `{"action":"HELP","stage":"REQUESTED"}` consulta instrucciones revisadas. Una acción explícita `HELP_REQUESTED` solicita atención de una persona, solo si `canContact` es verdadero; `RESOLVED` registra la confirmación del cliente y debe incluir `caseId` y `updatedAt` copiados del `helpRevision` del caso mostrado. No generes estos valores localmente. Ante `HELP_REPLY_CONFLICT`, recarga el caso y deja que el cliente lo revise antes de volver a confirmar. Cada escritura comprueba de nuevo la sesión y el permiso del dispositivo. Estas acciones no completan ni inventan respuestas a la encuesta. Las notificaciones de navegador abren la misma invitación con su progreso guardado. No incluyas respuestas en enlaces de correo ni cuentes aperturas, consultas GET o escáneres de seguridad como respuestas.