En las entradas previas, hemos mostrado cómo conectarnos a la API de OpenAI, hacer preguntas, recibir respuestas, sin contexto y con contexto. Naturalmente, con este conocimiento, podemos construir un Asistente Virtual (de aquí en adelante, AV) en cualquier plataforma, lenguaje o sistema de mensajería. Puesto que WhatsApp es el servicio de mensajería más común, ilustraremos cómo podemos integrar ambas tecnologías para obtener un AV completamente funcional.
Este tema será cubierto en una serie de entradas, cuya primera edición, es decir, esta publicación, estará dedicada a explicar cómo obtener las API Keys necesarias para utilizar la API de WhatsApp (administrada por Meta). La siguiente entrada tendrá como objetivo enviar mensajes a un número de WhatsApp usando la API, y la última: cómo integrar ambos conceptos junto con la API de OpenAI para construir un AV completamente funcional.
Obteniendo Api Key de WhatsApp, Clave secreta de la aplicación, e identificador del número de teléfono…
Los cuatro objetos listados en el título serán necesarios para usar la API. Para tenerlos, primero que todo, debes tener una cuenta de Facebook; idealmente, una cuenta antigua. En mi caso, puesto que no tenía, tuve que crear una y el proceso de verificación fue extremadamente engorroso.
Con la cuenta de Facebook en mano, ir a developers, y cliquear en empezar (esquina superior derecha, como en la imagen).
Luego, tienes que seguir con el proceso de registro llenando todos los campos de un formulario similar a este:
Una vez creada tu cuenta, tendrás acceso al dashboard de desarrollador, cuya vista es:
En tu caso, ninguna aplicación debería aparecer (yo ya tenía creada la mía); por tanto, debes crear una. Para hacerlo, solo debes cliquear el botón verde “Crear aplicación”. Cuando lo haces, verás un menú de este tipo:
En esta etapa, la parte más importante es “Casos de uso”. En esta sección, recomiendo elegir la opción “Otro” porque es más intuitiva.
Luego, verás un menú similar a este:
En ese menú, debes cliquear en el botón “configurar” de la sección “WhatsApp”. Una vez ahí, verás lo siguiente:
Para obtener el identificador de acceso (también conocida como la API Key de WhatsApp), vamos a “Configuración de la API” y generas un nuevo identificador de acceso, como se muestra en la siguiente imagen:
Además de esa clave, también necesitarás la clave secreta de la aplicación. Aquella la puedes obtener cliqueando “Configuración de la aplicación” y luego “Información básica”, para finalmente presionar el botón “Mostrar”, como se muestra en la siguiente imagen:
Con estos pasos, obtuvimos la API Key de WhatsApp (o identificador de acceso), y la clave secreta de la aplicación.
Obteniendo el identificador de verificación
El identificador de verificación puede ser definido por nosotros y se explicita de la siguiente forma: En primer lugar, debemos añadir una URL de devolución de llamada. En nuestro caso, será un archivo webhook.php que estará en nuestro servidor.
Luego, inventamos una clave y la escribimos en el input text llamado «Identificador de verificación».
A este fin, necesitamos que el archivo webhook.php esté en nuestro servidor y cumpla con la respuesta que Meta espera. En pocas palabras, al pulsar el botón verde “Verificar y guardar”, Meta envía una solicitud (request) a nuestro archivo con la clave que definimos y espera una respuesta HTTP 200. Esta lógica está implementada en PHP en el bloque de código siguiente:
if ($_SERVER['REQUEST_METHOD'] === 'GET') {
$mode = $_GET['hub.mode'] ?? $_GET['hub_mode'] ?? '';
$token = $_GET['hub.verify_token'] ?? $_GET['hub_verify_token'] ?? '';
$challenge = $_GET['hub.challenge'] ?? $_GET['hub_challenge'] ?? '';
if ($mode === 'subscribe' && $VERIFY_TOKEN !== '' && hash_equals($VERIFY_TOKEN, (string)$token)) {
header('Content-Type: text/plain; charset=utf-8');
http_response_code(200);
echo $challenge; // deveulve EXACTAMENTE lo que envía Meta
exit;
}
http_response_code(403);
echo 'Verification failed';
exit;
}En palabras, el código anterior captura los parámetros GET, hub.mode, hub.verify_token y hub.challenge de la solicitud de Meta. Si hub.mode es subscribe y el token recibido coincide con nuestro VERIFY_TOKEN (el que definimos nosotros), debemos responder con HTTP 200 y devolver exactamente el valor de hub.challenge en el cuerpo de la respuesta (texto plano).
A medida que nuestro código esté en producción, estamos listos para cliquear el botón “Verificar y guardar”. Cuando lo presionamos, Meta hace el request a nuestro webhook.php y valida que nuestro identificador es el correcto.
Como comprobación adicional de seguridad, es recomendable agregar a nuestro webhook.php el siguiente fragmento de código
if ($APP_SECRET && $headerSig) {
$expected = 'sha256=' . hash_hmac('sha256', $raw, $APP_SECRET);
if (!hash_equals($expected, $headerSig)) {
logit('Invalid signature. header=' . $headerSig . ' expected=' . $expected);
http_response_code(403);
json_out(['error' => 'Invalid signature']);
exit;
}
}En este bloque, $APP_SECRET es la clave secreta de la aplicación (que obtuvimos anteriormente). El objetivo de este código se puede resumir en dos puntos, primero, confirma que el emisor del request es Meta, y segundo, asegura que el body no fue modificado en tránsito.
Configuraciones finales…
Finalmente, en «Configuración» debemos activar messages, como se muestra en la imagen.
Además, debemos añadir un número de teléfono en el dropdown list con la leyenda «Selecciona un número de teléfono de destinatario», como se muestra en la siguiente imagen:
Por último, es imprescindible guardar el «Identificador del número de teléfono» que sale en la imagen anterior.
Resumen
Para enviar y recibir mensajes con la API de WhatsApp, el desarrollador debe tener cuatro códigos:
- Identificador del número de teléfono: Nos servirá como número de prueba para enviar y recibir mensajes.
- Identificador de verificación: Es útil para registrar nuestro webhook.
- API Key de WhatsApp: nos permitirá, entre otras cosas, enviar mensajes.
- Clave secreta de la aplicación: es fundamental para validar el mensaje.
Posteriormente, en la siguiente entrada, usaremos estos cuatro elementos para enviar un mensaje, condicionado a haber recibido uno antes.
José Miguel Muñoz Urra – jmunozu@pulki.es