Encuestas en WhatsApp y en tu app
Conserva las preguntas, respuestas y el progreso del cliente entre canales
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 y Canales y atención al cliente. Esta guía describe la integración técnica; habilitar un canal no sustituye su conexión ni el consentimiento del cliente.
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:
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 y respuestas rápidas en plantillas de Meta.
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.
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
GET /public/retention/mobile-survey
X-Bitelio-Mobile-Session: TOKEN_DE_SESION
X-Bitelio-Device: identificador-dispositivoLa 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:
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
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.