HelpMePlease
Iniciar sesión

Documentación

Todo lo que necesitás para integrar y sacar el máximo provecho de HelpMePlease.

1. Cómo embeber el widget

Pegá este snippet dentro del<body> de tu sitio, preferentemente antes del cierre de la etiqueta.

<script src="https://tu-dominio.com/widget.js" data-api-key="hmp_TU_API_KEY" async></script>
  • Reemplazáhmp_TU_API_KEY con la API key de tu sitio (disponible en el panel → Sitio → Instalación).
  • El widget solo cargará en páginas servidas desde el dominio configurado en el sitio.
  • Para múltiples entornos (staging, prod) creá un sitio distinto por entorno.
  • El script es async — no bloquea la carga de tu página.

2. Cómo escribir buenas entradas de conocimiento

La calidad de las respuestas depende directamente de la calidad del contenido de tu base de conocimiento. Algunas pautas:

Formato recomendado: Pregunta + Respuesta

Pregunta: ¿Cómo puedo cancelar mi suscripción?
Respuesta: Podés cancelar tu suscripción desde el panel → Cuenta → Suscripción → Cancelar. La cancelación es efectiva al final del período en curso.

  • Usá el lenguaje que usan tus clientes, no jerga interna.
  • Una entrada por tema — evitá mezclar múltiples temas en una sola entrada.
  • Incluí variantes de la pregunta si el tema tiene diferentes formas de preguntarse.
  • Actualizá las entradas cuando cambie la información.
  • Entre 50 y 500 palabras por entrada funciona bien para el modelo de embeddings.

3. Configurar escalación a Zendesk

Cuando el bot decide escalar, puede crear un ticket en Zendesk automáticamente.

  1. En Zendesk, generá un API token desde Admin → Apps and integrations → APIs → Zendesk API → Add API token.
  2. En el panel de HelpMePlease, andá al sitio → editar → sección "Escalación" → elegí "Zendesk".
  3. Completá los campos:
    • Subdomain: la parte dehttps://TU-SUBDOMAIN.zendesk.com
    • Email: el email del agente Zendesk con el que conectás
    • API token: el token generado en el paso 1
  4. Guardá. El próximo escalamiento creará un ticket en Zendesk con la transcripción.

4. Configurar escalación a Zammad

Similar a Zendesk, pero para instalaciones de Zammad.

  1. En Zammad, generá un token en Avatar → Profile → Token Access → Create. Asegurate de darle permisos de escritura en tickets.
  2. En el panel → sitio → editar → "Escalación" → elegí "Zammad".
  3. Completá:
    • URL: la URL base de tu Zammad (ej:https://soporte.miempresa.com)
    • API token: el token generado
  4. Guardá y probá con una conversación de prueba.

5. Escalación por webhook genérico

Si usás otro sistema de soporte, podés recibir las escalaciones como un POST HTTP con HMAC firmado.

HelpMePlease enviará unPOST a tu URL con este payload:

{  "conversation_id": 123,  "visitor_email": "[email protected]",  "reason": "El usuario preguntó sobre facturación",  "transcript": "[user] Hola\n[assistant] Hola, ¿en qué puedo ayudarte?",  "site": "Mi Tienda",  "escalated_at": "2026-05-26T14:32:00Z"}

El headerX-HMP-Signature contiene un HMAC-SHA256 del body usando el secreto configurado. Para verificarlo en Ruby:

expected = OpenSSL::HMAC.hexdigest("SHA256", ENV["WEBHOOK_SECRET"], request.raw_post)ActiveSupport::SecurityUtils.secure_compare(expected, request.headers["X-HMP-Signature"])