Table of Contents

TikTok

Definición

TikTok se integra a Lynn a través de tres canales independientes que comparten una misma cuenta/aplicación de TikTok Business, pero se comportan de forma distinta:

Dominio Naturaleza Comportamiento en Lynn
Direct Messages (DM) Conversación privada 1 a 1 Funciona como un canal conversacional normal: IVR, menús, flujo completo.
Comentarios Interacción pública sobre un video propio de la cuenta Se deriva directamente a un ejecutivo, sin bienvenida ni menú.
Menciones Monitoreo de menciones de marca, hashtags y comentarios donde se menciona a la cuenta Se deriva directamente a un ejecutivo, igual que Comentarios.

Requisitos previos (configuración del lado de TikTok)

Esta configuración la realiza una sola vez el equipo técnico/administrador antes de poder vincular el canal en Lynn:

  1. Cuenta de TikTok convertida a cuenta Business. Una cuenta personal no permite crear la aplicación ni exponerla como canal público vía API. Una cuenta Business tampoco puede configurarse como privada — debe ser visible públicamente para que la integración funcione.
    • En la app de TikTok: Perfil → Menú → Ajustes y privacidad → Cuenta → Cambiar a cuenta de empresa (Business Account), completando categoría, región, datos del negocio y sitio web.
    • Si TikTok solicita verificación de negocio, se debe cargar el documento aceptado según el país (ej. para Perú se validó que la consulta RUC es aceptada).
    • Configurar los permisos de mensajes directos de la cuenta para permitir la recepción de DMs de usuarios.
  2. Crear la aplicación en el portal TikTok API for Business, registrando nombre, sitio web, descripción, información del desarrollador, finalidad de uso y las URLs de redirección OAuth. Se debe usar específicamente la "TikTok account holder authorization URL" (no la de "Advertiser"), ya que es la que autoriza permisos sobre perfil, videos, comentarios, DMs y menciones.
  3. Guardar APP_ID/client_key y APP_SECRET/client_secret en un repositorio seguro — el secret no debe exponerse en frontend, logs ni documentación compartida.
  4. Solicitar los permisos (scopes) necesarios. Durante la revisión, TikTok Support puede exigir activar primero permisos base (Ad Account Management, CTX Events Management, Measurement) para iniciar la revisión de Business Messaging API, antes de habilitar los scopes funcionales:
    • Mensajería (DM): message.list.read, message.list.send, message.list.manage, más los de identificación de cuenta (user.info.basic, user.info.username, user.info.profile, etc.).
    • Comentarios: video.list (para obtener el item_id/video_id), comment.list, comment.list.manage.
    • Menciones: permisos Mentions > Content y Mentions > Comment (este dominio debe considerarse en validación hasta confirmar que la app tenga los permisos aprobados y que los endpoints respondan con esquema disponible).
  5. Completar el formulario de revisión de TikTok y, si corresponde, los cuestionarios de Data Security & Privacy Review. Si la aprobación tarda más de 10 días, se debe abrir un ticket en la mesa de soporte de TikTok.
  6. Autorización OAuth: una vez aprobados los scopes, la cuenta Business autoriza la aplicación (la URL de autorización se obtiene desde el propio portal de la app) y se intercambia el code recibido por access_token/refresh_token contra https://open.tiktokapis.com/v2/oauth/token/. El open_id devuelto se usa como identificador de negocio (business_id) en las APIs de mensajería, comentarios y menciones. El access_token debe renovarse antes de su vencimiento (recomendado: 30 minutos antes, o con un job programado cada 23 horas).

Método de integración (configuración del lado de Lynn)

  1. En el diseñador de flujos, clic derecho → Configurar Canal → Agregar canal, y seleccionar TikTok en la lista de canales. TikTok aparece como tres entradas independientes, cada una con su propio ícono distintivo: TikTok Direct Message, TikTok Comments y TikTok Mentions. Se puede partir por cualquiera de los tres; Lynn permite configurar los otros dos automáticamente con las mismas credenciales.

    Lista de canales, con las tres entradas de TikTok

  2. Completar el formulario Configurar Canal. Además de los campos generales del canal (Ambiente, Channel Id, Proveedor, División, Verificación de salud, Habilitar la depuración, No enviar mensajes en blanco, Deshabilitar eventos de escritura), la sección "Configuración asociada a TikTok [Direct Message/Comments/Mentions] (opcional)" trae los siguientes campos específicos del canal:

    Campo Variable Descripción
    Id de la cuenta de TikTok TIKTOK_ACCOUNT_NAME Identificador de la cuenta Business de TikTok vinculada.
    Id de la aplicación de TikTok TIKTOK_APP_IDENTIFIER client_key/APP_ID de la aplicación creada en el portal TikTok API for Business.
    Secret de la aplicación creada en TikTok TIKTOK_APP_SECRET client_secret/APP_SECRET de la aplicación.
    Tiempo de espera configurado para detectar inactividad y cerrar la interacción TIKTOK_TIMEOUT_SECONDS * Campo obligatorio (marcado con *).

    Formulario "Configurar Canal" para TikTok Comments, con los campos TIKTOK_ACCOUNT_NAME, TIKTOK_APP_IDENTIFIER, TIKTOK_APP_SECRET y TIKTOK_TIMEOUT_SECONDS

  3. Marcar la opción "Ejecutar la configuración para todos los canales relacionados" (viene preseleccionada) para crear los tres canales (Direct, Comentarios, Menciones) de una sola vez con los mismos parámetros, en vez de repetir la configuración tres veces.

  4. Presionar Verificar. Esto redirige a una ventana de inicio de sesión de TikTok:

    • Si la cuenta Business ya está autenticada en el navegador, Lynn recupera las credenciales automáticamente y genera el token de autorización.
    • Si no, TikTok solicita iniciar sesión (por ejemplo, escaneando un código QR desde la app móvil con la cuenta Business).

  5. Una vez verificado, Lynn guarda el token y confirma la creación de los canales.

  6. Verificar/actualizar la URL del webhook: cada canal muestra la URL de webhook actualmente configurada del lado de TikTok, comparada con la que Lynn recomienda para el ambiente/tenant en uso. Si difieren (por ejemplo, al mover la configuración de un ambiente de laboratorio al oficial), aparece un aviso y un botón Configurar que sobrescribe la URL en TikTok con la recomendada por Lynn (consumiendo una API del canal, no una edición manual). Cuando ambas URLs ya coinciden, el botón desaparece.

  7. Se recomienda usar íconos distintivos por canal en la lista de canales para diferenciarlos visualmente: un ícono de "enviar" para Direct Message, y el símbolo "@" para Menciones (Comentarios se deja sin ícono adicional).

Detalle de comportamiento por dominio

Direct Message

  • Funciona como cualquier canal conversacional: IVR con bienvenida, menús, y conversación continua identificada por el nickname del cliente en TikTok.
  • Límites de menú: máximo 3 opciones, ~20 caracteres por opción, ~40 caracteres en el título.
  • Medios que el cliente puede enviar a Lynn: video e imágenes. El audio técnicamente llega, pero la herramienta no ofrece actualmente una forma de descargarlo.
  • Medios que el ejecutivo puede enviar al cliente: solo imágenes. No es posible enviar una URL clickeable — TikTok no ofrece en su API un formato (ni siquiera HTML) que permita renderizar enlaces como clickeables; el texto de una URL llega al cliente como texto plano.
  • La interfaz web de TikTok no soporta menús ("este tipo de mensaje no es compatible, descarga la app de TikTok"); la app móvil sí los muestra correctamente.

Comentarios

  • El canal se configura típicamente sin bienvenida ni menú — la interacción se deriva directamente a un ejecutivo (Kyubo) apenas llega el comentario.
  • Cada comentario genera una sesión distinta, incluso si es del mismo cliente: el criterio de sesión es el ID del comentario (concatenación del ID de video + ID del comentario), no el nombre de usuario. Un mismo cliente comentando en dos videos distintos, o dos veces en el mismo video, genera dos sesiones separadas.
  • El resumen de la interacción que recibe el ejecutivo incluye: el título/caption del post (si el video no tiene título, este campo queda vacío), la URL del post, y el texto del comentario del cliente — como tres mensajes separados en el chat del ejecutivo (no consolidados en una sola burbuja). Este comportamiento es el mismo que usan actualmente en Lynn los demás canales de tipo comentario/mención público (Twitter/X, LinkedIn, Instagram, Facebook); no es una limitación exclusiva de TikTok, aunque es candidato a rediseño futuro específicamente para Kyubo.
  • La respuesta del ejecutivo se publica como respuesta pública al comentario original en TikTok (aparece bajo el comentario del cliente, con el logo/perfil de la cuenta de la marca — el mismo patrón que usan marcas como Netflix al responder comentarios).
  • Conocido (pendiente de mejora): al hacer clic en la URL del post desde el resumen de la interacción, actualmente se abre en la misma ventana de Kyubo, perdiendo la interfaz del ejecutivo; debería abrir en una pestaña nueva.

Menciones

  • Se comporta igual que Comentarios: deriva directo a un ejecutivo, sin bienvenida ni menú, y cada mención genera una sesión distinta.
  • El resumen de interacción incluye el título del post mencionado, su URL, y el texto donde se menciona a la cuenta.
  • La respuesta del ejecutivo se publica como respuesta social al comentario que generó la mención.
  • Para verificar manualmente en TikTok que la respuesta se publicó: en la cuenta de TikTok, ir a Actividad → Menciones y etiquetas.

Consideraciones generales

  • Solo el dominio Direct Message admite conversación privada y continua. Comentarios y Menciones son siempre interacciones sobre contenido público (el video debe ser público, no privado).
  • Si se elimina un comentario/mensaje del lado de TikTok después de que el evento ya llegó a Lynn, la sesión ya generada en Lynn no desaparece — el evento ya fue recibido y encolado.
  • Para pruebas, es posible usar una cuenta de TikTok personal propia convertida a Business, pero la aprobación de permisos por parte de TikTok puede tardar entre 1 y 2 semanas.
  • Es crítico no reutilizar la misma configuración de canal en el ambiente de testing y en producción simultáneamente.

Casos de uso

Prueba de extremo a extremo documentada (cuenta de prueba, canales 41/42/43 del tenant):

  1. Direct Message: un cliente escribe "Hola" al perfil de la marca → Lynn presenta un flujo de bienvenida con un menú de opciones (ej. "Inscripciones" y "Ayuda") → cualquiera de las opciones deriva a un ejecutivo disponible en el grupo de trabajo correspondiente.
  2. Comentarios: un cliente comenta un video público de la cuenta (ej. "Hola, qué buenos audífonos") → la interacción llega directo a un ejecutivo, sin pasar por flujo → el ejecutivo responde (ej. "Gracias por tu observación") → la respuesta se publica como reply público al comentario.
  3. Menciones: un cliente menciona la cuenta en un comentario ajeno (ej. "@marca te recomiendo esta serie", pudiendo mencionar a más de una cuenta a la vez) → llega como sesión de tipo "Mención TikTok" a un ejecutivo disponible → el ejecutivo responde y la respuesta queda visible como reply social bajo esa mención.