HaelDev
HaelDevHelpMePlease

Documentación

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

01

Cómo embeber el widget

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

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

Cómo escribir buenas entradas de conocimiento

La calidad de las respuestas depende de la calidad de tu base de conocimiento.

Formato recomendado: Pregunta + Respuesta

Pregunta: ¿Cómo puedo cancelar mi suscripción?Respuesta: Puedes cancelar desde el panel → Cuenta → Suscripción → Cancelar.
  • Usa el lenguaje que usan tus clientes, no jerga interna.
  • Una entrada por tema.
  • Incluye variantes de la pregunta.
  • Actualiza las entradas cuando cambie la información.
  • Entre 50 y 500 palabras por entrada funciona bien.
03

Configurar escalación a Zendesk

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

  1. En Zendesk genera un API token (Admin → Apps and integrations → APIs).
  2. En HelpMePlease: sitio → editar → Escalación → Zendesk.
  3. Completa subdomain, email y API token.
  4. Guarda. El próximo escalamiento creará un ticket con la transcripción.
04

Configurar escalación a Zammad

Similar a Zendesk, para instalaciones Zammad.

  1. En Zammad genera un token (Avatar → Profile → Token Access).
  2. En el panel: sitio → editar → Escalación → Zammad.
  3. Completa URL base y API token.
  4. Guarda y prueba con una conversación de prueba.
05

Escalación por webhook genérico

Si usas otro sistema, recibe las escalaciones como POST HTTP con HMAC firmado.

JSON
{  "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.

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