Guía paso a paso sobre cómo integrar herramientas web con la API cloud de WhatsApp

El tiempo es oro. A la hora de gestionar un negocio dar una respuesta rápida y eficaz a usuarios, clientes o compañeros de trabajo se convierte en una ventaja competitiva y una excelente carta de presentación. ¿Qué canales de comunicación podemos utilizar y cómo podemos integrarlos con el resto de nuestras herramientas de trabajo. En el siguiente artículo vamos a introducir y explicar los pasos básicos para integrar una herramienta web con la API cloud que tiene Whatsapp para empresas.

Características de la API Cloud de WhatsApp

Limitaciones técnicas de la API Cloud de WhatsApp

• Se permiten hasta 1.800.000 llamadas a la API en 24h.
• Va por número de teléfono (podemos comenzar con uno de pruebas que nos facilita la propia api).
• Se permiten hasta 5 números de teléfono por cuenta empresarial.

Precio y tarifas de la API Cloud de WhatsApp

Las primeras 1000 conversaciones de cada mes son gratuitas.

Puedes consultar todas las tarifas que Meta ofrece en el uso de esta API, pero recuerda que podemos asesorarte en la mejor opción y trabajar contigo en la integración de tus soluciones de negocio.

Registro y comienzo de la integración

En primer lugar, tenemos que crearnos una cuenta en Facebook (Meta), registrarnos como desarrollador y asociarla al doble factor de autenticación para comenzar a trabajar con esta herramienta.

Estos son los pasos para registrar nuestra cuenta creada como desarrollador:

• Con la sesión iniciada en Facebook (Meta) en este enlace.
• Aceptar condiciones y política de Meta.
• Verificamos la cuenta.
• Selecciona la ocupación que mejor describa a qué te dedicas.

Para ello, la cuenta que creemos en Facebook (Meta) debe tener activa la autenticación en dos pasos. La autenticación en dos pasos para una cuenta se activa de la siguiente manera:

• Accedemos a la cuenta que acabamos de crear en Facebook (Meta).
• Nos dirigimos a nuestro perfil (esquina superior derecha) y accedemos a configuración.
• En la pestaña de ‘Contraseña y Seguridad’ podemos activarlo, y elegir el método en que queremos recibir la doble autenticación (llave de seguridad en dispositivo compatible, envío de códigos a una aplicación de terceros, envío de códigos a un teléfono móvil).

Una vez tengamos esta cuenta activa y configurada con la doble autenticación, podemos dirigirnos a la página de desarrolladores de Facebook y crear nuestra primera aplicación.

Parar crear nuestra primera aplicación de WhatsApp seguiremos las siguientes indicaciones:

• Nos dirigimos a Mis Apps > Crear App.
• Seleccionamos el tipo de empresa (si nos solicitan seleccionar un caso de uso como parte del flujo de creación de la App, elegimos Otro y seleccionamos Empresa).
• Una vez tenemos la app creada, hacemos click en la misma y nos desplazamos hacia abajo hasta encontrar el producto “WhatsApp” y clickamos ‘Configurar’.

Configuración WhatsApp en Nueva APP

Una vez comencemos a configurar nuestra app para el uso de WhatsApp se nos pedirá seleccionar un administrador comercial preexistente (si ya tenemos uno) o bien el proceso de incorporación puede crearnos uno automáticamente (posteriormente podríamos añadir los datos de nuestra empresa)

Al seleccionarlo, se desembocarán las siguientes acciones:

• La App se asociará con la cuenta comercial que seleccionamos en el paso previo (o la que se creó automáticamente).
• Se generará una cuenta de WhatsApp Business.
• Se generará un teléfono de empresa de pruebas, el cual podremos utilizar para los primeros tests, con un número de mensajes ilimitado a cinco destinatarios distintos. (los números de teléfono reales que podemos incluir a posteriori no tienen limitación de destinatarios).
• Se nos redirigirá a WhatsApp (Primeros Pasos).

Primeros Pasos en WhatsApp Business como desarrollador

En la siguiente pantalla se nos empieza a mostrar la información técnica para poder realizar llamadas de prueba desde nuestra App recién creada:

 

Podemos enviar un mensaje de prueba desde esta pantalla sin necesidad de preparar ningún código para la llamada (se nos da la opción de probar desde la URL de nuestra App), sin embargo, atendiendo a los objetivos de este artículo, vamos a explicar como hacer las llamadas desde el código.

En esta pantalla WhatsApp (Primeros Pasos) se nos va a facilitar un token de acceso para poder llamar a la API de forma autorizada. (Es posible configurar este token para que sea permanente, pero por defecto no lo es – podemos configurar un token permanente en el apartado de nuestra App WhatsApp > Configuración > Aprende a crear un identificador permanente).

En las cabeceras de esta llamada (headers), tenemos que incluir en Authorization, como token Bearer el valor del token que se nos ha dado para estar autenticados en estas llamadas.

Enviando nuestro primer mensaje de prueba con la App de WhatsApp

Debemos realizar los siguientes pasos para realizar ese envío

• Debemos iniciar la conversación desde la cuenta empresarial. Una vez que tengamos respuesta del destinatario de ese primer mensaje, tenemos la conversación ‘abierta’ en las próximas 24h.
• Para enviar un mensaje válido en una App recién creada, debemos utilizar una template (plantilla) existente.
• Por defecto, si no administramos nuevas plantillas, tenemos disponible la plantilla con el nombre ‘hello_word’ (para la primera prueba).

URL de llamada para envío de mensajes:

Cabeceras de llamada para envío de mensajes en WhatsApp Business

->  Authorization: Bearer [valor del token proporcionado]’
-> ‘Content-Type: application/json’

          Body (JSON) de la llamada POST para enviar el mensaje:

{

«messaging_product»: «whatsapp»,

«to»: «34619666666»,

«type»: «template»,

«template»: {

«name»: «hello_world»,

«language»: {

«code»: «en_US»

}

}

}

Importante para realizar la llamada con éxito: utilizar una template (plantilla) existente. Por defecto tenemos disponible la plantilla hello_word con el idioma inglés (en_US).

Esta plantilla ya contiene un valor de texto y se enviará ese contenido al destinatario indicando en To.

Una vez tenemos la conversación con el destinatario ‘abierta’ podemos enviar directamente un mensaje tipo texto (en lugar de plantilla – sin embargo para ‘abrir’ la conversación, el primer mensaje tiene que ser una plantilla de las existentes) de la siguiente manera:

{

«messaging_product»: «whatsapp»,

«to»: «34619666666»,

«type»: «text»,

«text»: {

«body»: «mensaje redactado al Whatsapp de 619666666»

}

}

Si queremos enviar sin embargo otra plantilla que no tengamos por defecto, se hace necesario administrarla.

(Como se ha indicado arriba, para poder dar una conversación por iniciada o ‘abierta’ durante las próximas 24 horas, nuestra aplicación empresarial deberá ser la primera en iniciar la comunicación, y recibir una respuesta del destinatario. Esto funciona igual con indiferencia de si usamos el type template o text en nuestro envío).

Administración de plantillas disponibles para la App

Desde el siguiente apartado podemos administrar las plantillas de las que dispondrá nuestra App:

Nos indica que le seleccionemos un idioma, y nos permite indicar el texto que lleva la plantilla.

Las plantillas deben pasar por la aprobación de Meta, pero suele ser un proceso rápido.

Recepción de Mensajes para el destinatario

Para tener la app que estamos creando lista para recibir mensajes de respuesta desde los destinatarios, y realizar cualquier acción con las respuestas, el primer paso que tenemos que realizar es diseñar un web service que actue como Webhook para la app.

Creación de un webhook para WhatsApp

Se hace necesario crear un web Service API REST. Si tenemos en el servicio algún .svc que queramos reaprovechar, podemos utilizar ese, o bien podemos definir un .svc específico para albergar la llamada al Webhook (por ejemplo WhatsappReceiver.svc).

También podemos reutilizar algún webhook que nos proporcione una herramienta de terceros, pero esto va a conllevar un coste que si diseñamos nosotros mismos el webhook, no.

Creación del punto de espera (llamada WS):

La llamada que nosotros tenemos implementada para poder recibir mensajes desde los destinatarios es la siguiente:

Hemos reaprovechado un .svc que ya teníamos en nuestro REST (WebService.svc), por tanto la URL para nuestro Webhook es la siguiente:

https://[servidor]/WebService.svc/webhooks

Vamos a estudiar los distintos parámetros que entran a esta llamada:

@object: parámetro por defecto que nos va a enviar la API de Whatsapp a nuestro webhook cuando responda el destinatario, y por tanto lo necesitamos como parámetro de entrada (con el nombre object, se pone la @ porque es palabra reservada).

@entry: listado de objetos en JSON que nos va a enviar la API de WhatsApp a nuestro webhook cuando responda el destinatario. Cada elemento consta de lo siguiente:

Objetos JSON de entry (elementos de la lista que entra como parámetro al webhook):

              id: Identificador de la cuenta de WhatsappBusiness.

changes: Listado de cambios detectados (respuestas), que consta de elementos con la

siguiente estructura:

Objetos JSON de changes (elementos de la lista que representa changes):

                            value: Objeto que contiene todo lo referente al mensaje que se acaba de responder desde el destinatario.

                            field: cadena de texto. ámbito de la API que nos envía el cambio al webhook (para el caso que nos ocupa, llega messages).

                            Objetos JSON de value (elemento que contiene el valor de los cambios) 

                            messaging_product: Cadena de texto. Indica el producto que nos envía el cambio (para el caso que nos ocupa, llega whatsapp).

                            metadata: Objeto que contiene ciertos metadatos importantes del mensaje.

                            contacts: listado de objetos que referencian al contacto (destinatario) que nos está enviando el mensaje.

                            messages: listado de objetos que referencian al mensaje que estamos recibiendo.

                            Objetos JSON de metadata (pertenece a objeto value):

                            display_phone_number: Cadena de Texto. Numero al que se ha enviado el mensaje (en este caso el proporcionado para pruebas al crear la app).

                            phone_number_id: Cadena de Texto. Identificador interno del teléfono al que se ha enviado el mensaje.

                            Objeto JSON de contacts (listado que pertenece al objeto value):

                            profile: Objeto JSON con información acerca del perfil del destinatario que nos está enviando el mensaje.

                            wa_id: Cadena de Texto. Identificador del contacto (en los casos comprobados coincide con el teléfono que está enviando el mensaje – con prefijo de país incluido).

                            Objeto JSON de profile (pertenece a contacts – listado que pertenece a objeto value):

                            name: Cadena de Texto. Nombre del destinatario que nos envía el mensaje (el que tenga puesto el destinatario en su WhatsApp).

                            Objeto JSON de messages (listado que pertenece al objeto value):

                            from: Cadena de Texto. Número de teléfono del destinatario que está enviando el mensaje (con código de país incluido).

                            id: Cadena de Texto. Identificador del mensaje que se presenta encriptado.

                            timestamp: Cadena de Texto. Representa la fecha en que se ha enviado el mensaje, pero se presenta en numérico (tendremos que convertirlo para tratar con ella).

                            text: Objeto JSON que incluye el contenido del mensaje que se está enviando.

                            type: Tipo de mensaje que estamos recibiendo (ante una respuesta escrita estándar, muestra text).

                            Objeto JSON de text (incluido dentro del objeto elemento del listado messages): 

                            body: Cadena de Texto. Incluye el texto enviado en el mensaje.

Necesitamos definir toda esta estructura de objetos en nuestro código para que los mensajes recibidos en respuesta a nuestros inicios de conversaciones se reciban en el webhook que diseñemos.

Una vez tengamos el webhook personalizado diseñado, debemos dirigirnos a developers.facebook.com y configurarlo en nuestra App.

Para ello, dentro de nuestra App, nos dirigimos al menú lateral WhatsApp, desplegamos, y nos dirigimos a configuración:

Una vez estamos en configuración, veremos una pantalla similar a la siguiente:

Se explican ahora los pasos para configurar el webhook en nuestra App:

1. Clicamos ‘Configurar un Webhook’ (nos aparecerá en una App que todavía no lo tenga configurado).
2. Aparece un cuadro de dialogo que nos pide una URL (URL de la llamada al webhook que hemos diseñado – lo que en la captura vemos de amarillo) y un identificador de verificación.
3. Clicamos entonces verificar y guardar.
4. Si el webhook se ha diseñado siguiendo los patrones especificados en los puntos anteriores de este artículo, la App debería validar la verificación y quedaría configurada para recibir las respuestas de los destinatarios.
5. Ahora, si tenemos desplegado el servicio donde hemos diseñado nuestro webhook (debería estar desplegado también para configurar la App), podemos probar a enviarnos un mensaje a nosotros mismos desde el código con nuestro Identificador de App y desde nuestro móvil enviar respuesta. Si tenemos la trazabilidad de lo que está entrando al webhook, comprobaremos como el mensaje ha llegado y podemos trabajar con la estructura mencionada arriba para poder realizar acciones con ellos.

Siguientes pasos para la configuración y uso de la API de WhatsApp

Con nuestra App configurada para enviar y recibir mensajes (y las acciones correspondientes a la recepción de mensajes implementadas), podemos empezar a pensar en nuestra aplicación para usos de caso en producción. Para ello es necesario:

Configuración número de teléfono real

Para evitar la limitación de cinco usuarios por teléfono (que ocurre con los teléfonos de prueba proporcionados por la API) debemos configurar un teléfono real para que salgan los mensajes desde el mismo en nuestra App.

Si queremos seleccionar un teléfono ya existente para una cuenta empresarial o cliente de WhatsApp, debemos migrarlo a WhatsApp Business (una vez migrado perderemos el acceso de ese teléfono a la cuenta empresarial o cliente de WhatsApp). Guía para realizar este paso.

Existen una serie de reglas para los teléfonos que podemos seleccionar, que se nos explican en este enlace.

Una vez tengamos el número de teléfono real seleccionado, procedemos a añadirlo a nuestra App:

Consetimiento

Debemos obtener consentimiento explícito de los usuarios para mantener conversaciones proactivas iniciadas por la empresa.

Este consentimiento debe seguir una serie de reglas:

• Para ‘abrir’ nuestra conversación con un destinatario para las próximas 24h, el primer paso debería ser (antes incluso de enviarle la primera plantilla que inicie la conversación), enviarle un consentimiento que el destinatario debe aceptar para recibir el mensaje y poder responder.
• Existen varios métodos para obtener el consentimiento del usuario (SMS, Sitio Web, Hilo de WhatsApp, Por teléfono (proceso de respuesta de voz interactiva) o en persona o en papel).

Este consentimiento debe cumplir una serie de requisitos:

• Debe indicar claramente que una persona quiere recibir mensajes de la empresa vía WhatsApp.
• Debe manifestar claramente el nombre de la empresa que desea enviar los mensajes. (y de la que una persona acepta recibir)
• Debe cumplir la legislación aplicable.

Se debe seguir optimizando la experiencia del usuario cuando obtenemos el consentimiento. Estas son algunas sugerencias útiles:

• Los usuarios deben esperar los mensajes que reciben (podemos definir consentimientos específicos para una categoría de mensajes, etc.)
• Debemos proporcionar instrucciones claras acerca de como retirar un consentimiento de categorías especificas de mensajes, y respetar este consentimiento.
• Debemos asegurarnos de que los procesos de obtención y retirada de consentimiento son intuitivos y claros para el usuario.
• Informar con claridad del valor de esta recepción de información para WhatsApp.
• Supervisar la calificación de calidad, especialmente al diseñar nuevos consentimientos.

En este artículo se han explicado los pasos básicos para disponer de nuestra App para envío y recepción de mensajes con una cuenta empresarial, para utilizar esa App creada en Meta en nuestra aplicación web.

Puede resultar una herramienta muy interesante en unos tiempos donde, pese a seguir con el uso de SMS y otro tipo de comunicaciones, WhatsApp es una herramienta de comunicación potente, muy implantada y de las más utilizadas.

Quieres incluir esta y otras integraciones en la metodología de trabajo de tu negocio. Contacta con nosotros para que podamos ayudarte.