HSMs (español)

Owned by Sebastian Arena
Last updated: Sept 19, 2024
14 min read

¿Qué son?

La sigla HSM refiere a Highly Structured Messages, básicamente mensajes basados en un template.
No son directamente mensajes estáticos, son templates, que permiten alguna variabilidad en el contenido que entregan, permitiendo con placeholders a lo largo del texto, customizar la respuesta para diferentes usuarios.

Ejemplo #1

⛈ Según datos del Servicio Meteorológico Nacional, el Municipio de Tigre 🐯 informa que rige en el área un alerta por tormentas fuertes y sudestada con una pleamar de {{1}} a las {{2}} hs 🕐

Este mensaje tiene {{1}} y {{2}} como placeholders de texto, que al momento de enviar el HSM deberán ser reemplazados con un texto que puede tener cualquier forma y tamaño, en este caso, horarios. Dejando así la posibilidad de reutilizar el mismo mensaje en diferentes ocasiones que se lo necesite.

Ejemplo #2

{{1}}, ya hemos cargado la documentación que nos enviaste! 🙂 Para terminar realizá la capacitación online para aprender como hacer el mejor uso de la aplicación y completá el Test de aptitudes para conductores. Continuar con el proceso de inscripción: {{2}}

Este mensaje también tiene 2 placeholders, en este caso actuando de forma que {{1}} sirve para poder enviar el nombre de la persona contactando y {{2}} para enviar un link especial para cada persona.

Características

  1. Estos mensajes solo funcionan dentro de la plataforma WhatsApp

  2. Tienen un costo de envío por cada uno que se quiera enviar

  3. Deben ser pre-aprobados por WhatsApp para su funcionamiento, que normalmente lleva entre 1 y 5 días de aprobación. En caso de desaprobar, WhatsApp no suele dar ningún tipo de información de porqué.

  4. Cada template solo puede tener 1 mensaje pre-aprobado, es decir una “globa” de mensaje que será enviada al usuario final. Múltiples “globas” representan múltiples mensajes.

  5. Pueden contener opcionalmente placeholders de texto para customizar la experiencia (como descripto arriba). Pueden ser mensajes fijos sin ningún problema.

  6. Pueden tener múltiples idiomas pre-configurados, para poder elegir al momento de enviar el mismo, con que idioma se envía. No es necesario especificar todos los idiomas al momento de la pre-aprobación, se pueden ir agregando con el tiempo.

  7. Los textos una vez aprobados no pueden ser editados, y si necesita cambiar, se deberá enviar a pre-aprobar un nuevo texto.

  8. Tienen diferentes tipos, pero normalmente utilizamos “MARKETING”. Podria ser que en ocasiones se deba utilizar otra categoría. Las conocidas al momento son las siguientes:

    1. MARKETING

    2. UTILITY

    3. AUTHENTICATION

Proceso de aprobación

Al momento ningún proveedor ofrece una API para poder gestionar los HSM, lo cual implica que desde el Dashboard de Chat-Tonic no se pueden gestionar tampoco.

Infobip

Se debe gestionar mediante un ticket a soporte.

GupShup

Desde el panel de control para el cliente se pueden gestionar la creación y verificación de estado de todos los HSM del cliente. También se puede gestionar esto via API con GupShup directamente.

 

Utilización dentro de Chat-Tonic

Envío de HSM

Una vez aprobado el HSM, automáticamente se puede proceder a la utilización del mismo dentro de Chat-Tonic. No hay que realizar ningún paso adicional.

Las vías para realizar esto son:

  1. Integración con la API del proveedor directa: Método no recomendado, pero es posible si ya existe previamente por parte del cliente una integración que pretenden seguir manteniendo. Utilizado de esta forma el envío pierde algunas funcionalidades que podemos ofrecer a través de Chat-Tonic, descriptas debajo.

  2. Integración con nuestra API: Muy similar a las APIs ofrecidas por los proveedores, y muchas veces aún más sencillas. La documentación de cómo enviar HSM puede ser encontrada aquí, en nuestra wiki pública.

  3. Subir un Excel en el Dashboard (sección HSM): Esta forma es bastante amigable para el cliente una vez que se tiene el entendimiento de cómo funcionan los HSM. Solo basta generar un Excel con ciertas columnas, y subirlo al sistema, para poder enviarlo. A continuación esta explicado el funcionamiento del Excel. Este documento será suficiente para poder generar un Excel modelo para cualquier HSM que se necesite enviar en cualquier cuenta.

    Se debe crear un Excel cuya primer fila debe tener todos los nombres de las columnas especificadas abajo. Aún cuando la columna este en blanco siempre.
    Adicionalmente el nombre de la planilla debe ser campaign. Revisar bien esto antes de subir el Excel, de lo contrario no se procesará. Y revisar que sea el nombre de la planilla (típicamente Sheet1). El nombre del archivo que se suba debe ser customizado, dado que posteriormente se usa dicho nombre como nombre de campaña de envío masivo, para el historial de HSM enviados. De esa forma, un archivo que se llame “AlertaSudestada-08-05-2020.xlsx” tendrá como nombre de campaña “AlertaSudestada-08-05-2020”.

    Columnas:

    • phone: el número de teléfono al cual enviar el HSM. El formato acepta teléfonos muy variados. Internamente Chat-Tonic aplica una limpieza donde básicamente elimina caracteres típicos que aparecen al escribir un número de teléfono. Por ejemplo, un teléfono: “+54 (911) 1234-5678” es transformado internamente como “5491112345678”. Normalmente se recomienda incluir en el teléfono toda la información internacional para garantizar poder enviar el HSM correctamente. Sobre todo necesario cuando se quiere enviar desde un teléfono de un país hacia otro país.

    • elementName: El nombre del HSM que fue cargado. Suele ser un nombre que consta de letras, numeros, guiones y guiones bajo. Por ejemplo: recontacto, alerta_sudestada, confirmacion_envio_01

    • languageCode: El código de idioma con el cual se cargó el texto del HSM aprobado. Este puede variar desde un código de 5 dígitos o 2 dígitos. Por ejemplo: es-AR, es, en-US, en, pt-BR, pt. Este dato habrá que verificarlo en cada plataforma donde se cargó el HSM.

    • languagePolicy: Debe decir siempre DETERMINISTIC

    • flag: (opcional, puede dejarse en blanco) Una variable libre de uso interno a Chat-Tonic. Explicada debajo en Integración con un chatbot.

    • parameter: (opcional, puede dejarse en blanco) Representa el primer parámetro placeholder ({{1}}) a ser reemplazado en el mensaje. Dado que cada linea del Excel puede referir a un HSM template diferente, es importante conocer cuales son los parámetros que tiene cada uno, para poder incluir en el Excel todas las columnas de parameter que sean necesarias. El nombre de la columna siempre tiene que ser parameter sin importar si es el 1 o el 10. El Excel se lee en orden de columnas, y se asume que el la primer columna parameter pertenece al parámetro {{1}} y la décima columna parameter pertenece al parámetro {{10}}.

    • …

    • parameter

  4. Envío en conversaciones ya existentes: Dentro de la sección de Conversaciones es posible enviar HSMs directamente a un usuario del chatbot. Es requisito para hacer esto que el HSM deba estar cargado previamente en la sección HSM Templates (explicado abajo).

    Para acceder, se debe ir Conversaciones. Seleccionar una conversación de WhatsApp, y arriba de la caja de escribir texto aparecerá una pequeña flecha que al expandirse mostrará todos los HSM Templates cargados:



    Una vez que se elija el HSM aparecerá un segundo popup para elegir el idioma a enviar:



    Finalmente al elegir el idioma, aparecerá el texto del HSM con los campos a completar en caso de que existieran



  5. Envío en conversaciones nuevas: Dentro de la sección de HSM será posible enviar HSM individuales utilizando los HSM Template cargados para simplificar el proceso. Esta funcionalidad esta aún en desarrollo.

Reporte de HSM

Todos los HSM que se envíen a través de Chat-Tonic utilizando cualquiera de los métodos mencionados anteriormente dejará un registro del estado de dicho HSM para su posterior seguimiento.

Los reportes se pueden descargar en dos formatos.

El primer informe simplemente exporta la información provista en el reporte de HSM en pantalla, para poder procesarlo en otras plataformas de necesitarse.

El según informe informa la cantidad de HSM enviados en cada mes, a modo de poder tener una comparativa frente a lo que los integradores informen, con propósitos de revisión para la facturación.

HSM Templates

Existe la posibilidad de importar los HSMs aprobados en un cliente a nuestro Dashboard. Esta posibilidad, completamente opcional, habilita las siguientes funcionalidades del lado de Chat-Tonic:

  1. Activa el sistema de envío de HSM en conversaciones ya existentes como se indica mas arriba en el punto 4.

  2. Activa el sistema de envío de HSM individuales en conversaciones no existentes cómo se indica más arriba en el punto 5.

  3. En caso de querer enviarse un HSM a una conversación que este abierta, es decir, que aún esté dentro del periodo de gracia de 24hs para poder responder, Chat-Tonic envía un mensaje al usuario, ahorrando el costo del envío de HSM al cliente.

Por lo cual, el funcionamiento vía Excel o API funciona sin problemas aunque no estén cargados los HSM templates.

Integración con un chatbot

En sí los HSM son mensajes individuales que se envían a los usuarios, que en ningún momento tienen conexión con un chatbot.

Chat-Tonic desarrolló algunas capacidades que permiten unir el envío de HSM con un chatbot en diferentes circunstancias.

Responiendo a un HSM

Existen algunos HSM que tratan de generar engagement en el usuario, y es posible que se envíe algún tipo de pregunta que el usuario deberá responder. Para esto Chat-Tonic al enviar un HSM, guarda dentro de la conversación, el nombre del HSM enviado. Al usuario responder la pregunta, hay una chance por única vez de poder procesar la respuesta, sabiendo que el HSM enviado esta guardado en la conversación. De no procesarse el HSM al recibir el primer mensaje, se elimina el registro de la conversación.

Esto quiere decir qué se puede entrenar una AI con diferentes intenciones, y al momento de cargar la condición, se puede incluir información extra que chequee que el ultimo mensaje enviado sea un HSM, para poder.

Ejemplo #1 - Intenciones

Texto del HSM

Hola {{1}}! Te estamos contactando de Cabify. El otro día empezaste el proceso de darte de alta como conductor. Querés terminar el proceso?

Respuesta afirmativa

Iniciar el proceso de onboarding

Respuesta negativa

Preguntar porque no quiere continuar

Para esto, se generan inicialmente dos flows que manejaran por un lado la respuesta positiva y por otro lado la respuesta negativa. Adicionalmente se utilizó la intención de afirmativo y negativo para poder unir las respuestas posibles al HSM y poder ir a los flows.

Condición para respuesta negativa:

Condición para respuesta afirmativa:

Explicación de criterios utilizados:

  1. El HSM se guarda en la conversación en la variable cxt.user.context.__hsm.elementName, con lo cual basta agregar esta variable junto con el nombre del HSM (en este caso terminar_onboarding) para poder procesar únicamente cuando se cumpla esta condición (adicionalmente cabe aclarar que al enviar un HSM la plataforma guarda en forma automática tambien la variable cxt.user.context.__hsm.parameters que contiene un array de los parametros enviados, para poder utilizarlos en el procesamiento del mensaje si llegara a necesitarse; conviene siempre utiliza la variable flag para estas situaciones, pero la posibilidad existe)

  2. La condición se carga con prioridad alta, de manera de poder obtener la respuesta del usuario, calcular la intención, y poder priorizar la respuesta ante un HSM antes que todo, dado que tenemos una sola chance de procesar la respuesta antes de que se borre el registro del envío del HSM.

  3. La condición de respuesta afirmativa no lleva intención, porque si bien podríamos agregar la intent:affirmative hay un conjunto de respuestas que no serán ni afirmativas, ni negativas, y fue opción del cliente forzar ir por el camino de respuesta positiva.

Ejemplo #2 - Botones

Una pregunta bastante típica es si los HSM pueden mostrar botones.

Hace poco tiempo WhatsApp agrego esta posibilidad, la cual aún no está integrada del lado de Chat-Tonic para los diferentes proveedores. Estamos trabajando activamente para poder implementarla.

Por el momento se puede incluir en el HSM el texto necesario para que aparezcan las diferentes “opciones”. Del lado de Chat-Tonic, al no estar creadas las opciones desde el chatbot, estamos muy limitados a cómo poder validar la respuesta. Podríamos únicamente validar 1 letra, como a, b, c. Y podríamos adicionalmente unir cada respuesta a una intention / keyword de AI para mejorar la oportunidad de capturar la respuesta correcta.

Utilizando información de un HSM

El cliente puede querer enviar hacia Chat-Tonic junto con el HSM, información extra sobre la razón del envío del HSM, de manera de poder validar la información que será de utilidad en el procesamiento de la respuesta del HSM.

Es para esto que el parámetro flag entra en juego.

El mismo puede recibir información en forma String, que puede ir desde una simple palabra a un JSON más complejo.

Usemos el parametro flag para enviar metadata sobre el HSM

Ejemplo #1

En el caso anteriormente explicado de Cabify, el cliente quería al momento de iniciar el proceso de onboarding, verificar si el email con el que la gente había iniciado el proceso era valido. Para lo cual en el parámetro flag me envía el email de las personas que estaba contactando por HSM. Al momento de iniciar el onboarding en caso afirmativo, el flag está guardado en cxt.user.context.__hsm.flag, que será procesado por el chatbot según lo que el desarrollador indique conociendo que se envía en cada caso. En el caso de Cabify, sabíamos que era un email enviado, y lo procesábamos como tal.

Ejemplo #2

Puede usarse el HSM por ejemplo para enviarse cotizaciones sobre productos. Y es posible que la cotización este personalizada para el usuario, en cuyo caso tendrá un ID de cotización único. Esta información puede viajar invisible al usuario en el flag que en caso de aceptar el mismo la cotización, se puede informar al cliente cuál era la cotización aceptada.

Integración con Customer Service

Existe en el Dashboard de Customer Service la posibilidad de configurar un HSM de recontacto, que servirá en los casos que el operador quiera enviar un mensaje al usuario final para revivir una consulta que ha pasado más de 24hs desde su respuesta. Típicamente muy útil para consultas que se reciben durante el fin de semana, y que el Lunes ya no se pueden responder porque pasaron más de 24hs.

Esta funcionalidad es opcional de activarse.

Basta con consultar con el cliente cual es el HSM que quisieran enviar para el recontacto.

Una vez aprobado, se configura dentro del App de Customer Service, y automáticamente pasadas las 24hs de respuesta en WhatsApp, se presentará en la UI mediante un botón la posibilidad de enviar el HSM de recontacto.

Para evitar costos excesivos, se aclara al operador que el HSM tiene costo, y solo se permite enviar el recontacto una única vez por consulta.

Acceso por API de Chat-Tonic

Envío de un HSM simple

El API call tiene una autenticación muy simple mediante un API key que proporciona Chat-Tonic, y que se envía en el header o como querystring.

El API call recibe los siguientes parámetros en el body, en formato JSON:

“id”: que es el numero de teléfono, con o sin + adelante, y en forma completa, por ej.: +54912349876

“hsm”: que es un objeto de JSON donde se pasan los datos específicos del HSM que se seleccionó. Particularmente se pasan 2 datos que determinan el “template” a utilizar (elementName), y luego se pasa parameters que son las variables que auto-completan el template. Por ej. Puede ser que un HSM sea algo “Bienvenido {1} a nuestro servicio de atención de WhatsApp”. Donde {1} se reemplaza por el primer parámetro del array, y así sucesivamente si hubiera mas.

Dentro de este objeto tambien se declara la media a enviar, se debe proveer un objeto como el siguiente:

media = { from: 'URL', type: 'image'|'video'|'document' url: 'https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg' }

“buttonParameter“: es un string, obligatorio solamente en los casos donde se requiera enviar un boton de tipo “call to action - url dinamico“, para esto primero debe crearse el template dentro de la plataforma de chat-tonic con este tipo de boton.

“flag”: es un string, opcional. Sirve para la comunicación hacia el bot de parámetros opcionales, para capturar datos que de otra manera el bot no podría recibir. Por ej: se podría usar para enviar el email de la persona que se esta contactando, para luego al procesar la respuesta del usuario al HSM, se pueda utilizar dicho email para algún flujo particular.

El siguiente es un ejemplo en CURL:

  • appCodename es el codename de aplicación, especificado por Chat-Tonic, y es particular para cada cliente

  • accountId es el id de la cuenta, especificado por Chat-Tonic, y es particular para cada cliente

  • platform especificado por Chat-Tonic, y es particular para cada cliente según la plataforma de WhatsApp que haya contratado:

    • whatsapp-gupshup para clientes de GupShup

    • whatsapp-infobip para clientes de Infobip

    • whatsapp-clickatell para clientes de Clickatell

    • whatsapp-360dialog para clientes de 360 Dialog

  • appToken (indicado en el header de Authorization) es especificado por Chat-Tonic, y es particular para cada cliente, para poder autenticar las llamadas realizadas

  • elementName: el nombre for the HSM, especificado por Chat-Tonic

curl -X POST \ https://chat-tonic.com/api/v1/:appCodename/:platform/:accountId/sendhsm \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer :appToken' \ -d '{ "id": "+54911", "hsm": { ""elementName": "template_name", "parameters": [] }, "flag": "opcional"}’

Envío de una campaña de HSMs

El API call tiene una autenticación muy simple mediante un API key que proporciona Chat-Tonic, y que se envía en el header o como querystring.

El API call recibe los siguientes parámetros en el body mediante un POST del tipo multipart que permita enviar archivos.

“upload”: requerido, el nombre del key donde se deben enviar el archivo en alguno de los formatos soportados

“platform”: debe ser enviado en el querystring, indica el nombre de la plataforma que se está usando para enviar los HSMs, debe ser alguna de las siguientes opciones:

whatsapp-gupshup para cuentas de GupShup
whatsapp-infobip para cuentas de Infobip
whatsapp-clickatell para cuentas de Clickatell
whatsapp-360dialog para clientes de 360 Dialog

“accountId”: debe ser enviado en el querystring, indica el ID de la cuenta que se está usando para enviar los HSMs

“date”: opcional, debe ser enviado en el querystring, una fecha en formato ISO 8601, que define cuando la campaña debe ser enviada. Debe ser una fecha en el futuro.

Los tipos de archivo soportados son:

  • XLS: Con el siguiente formato de columnas:

    • A: "phone" / “id”

    • B: "namespace"

    • C: "elementName"

    • D: "languageCode"

    • E: "languagePolicy"

    • F: "flag"

    • G: “buttonParameter“

    • H: "media.from"

    • I: "media.type"

    • J: "media.url"

    • K: "parameter"

    • L: "parameter"
      ...

      IMPORTANTE: Los "parameter" se van a enviar en el orden en el que se carguen, si la celda no tiene valor no se envia el parámetro.

      IMPORTANTE: Utilizar cabeceras en cada propiedad descripta para poder identificarlas.

      IMPORTANTE: El nombre de la sheet debe ser "campaign"

  • CSV: Separado por "," (comas) con el siguiente formato:

    "phone (o “id”), namespace, elementName, languageCode, languagePolicy, flag, media.from, media.type, media.url, buttonParameter, parameter, parameter,...\n"


    IMPORTANTE: Los "parameter" se van a enviar en el orden en el que se carguen, si la celda no tiene valor no se envia el parámetro.

    IMPORTANTE: Utilizar cabeceras en cada propiedad descripta para poder identificarlas.

  • JSON: Un array de objetos con las propiedades:

    • phone / id

    • namespace

    • elementName

    • languageCode

    • languagePolicy

    • flag

    • parameters (array of string)

    • buttonParameter

    • media (object)

  • ZIP, GZ, TAR: Cualquiera de los formatos anteriores pero comprimido. Ej: hsms.xlsx.zip

curl --X POST \ 'https://chat-tonic.com/api/v1/demo/hsm/campaign/upload?platform=:platform&accountId=:accountId' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer :userToken' \ --form 'upload=@"~/hsm_campaign.json"'

GET HSMs enviados

Para obtener ya sea un HSM enviado o una campaña de HSMs enviados mediante un archivo, se debe enviar, dentro del parametro query, el campo campaignId provisto en el response de la api donde se genero el envio.