Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Configuración de flujos dinámicos
Un flujo dinámico llama a su propio punto final HTTPS durante el tiempo de ejecución para obtener el contenido de la pantalla y decidir la navegación. Los flujos estáticos definen todas las pantallas del JSON de Flow. En cambio, los flujos dinámicos utilizan la data_exchange acción para solicitar datos a tu punto final cada vez que un usuario navega entre las pantallas. Esto permite disfrutar de experiencias personalizadas y basadas en datos, como mostrar a un usuario sus pedidos pendientes, validar los datos introducidos desde el servidor o establecer sucursales en función de una decisión de backend.
Cuando un usuario interactúa con un flujo dinámico, Meta llama directamente a tu punto final con una solicitud cifrada. Su punto final descifra la solicitud, ejecuta su lógica empresarial, cifra la respuesta y la devuelve a Meta. La solicitud y la respuesta cifradas pasan directamente entre Meta y tu terminal, por lo que AWS End User Messaging Social nunca tiene acceso al contenido descifrado de estos intercambios. AWS End User Messaging Social gestiona el plano de control: crea y actualiza Flows, carga la clave pública de cifrado y entrega webhooks sobre el estado de Flow.
Para configurar un flujo dinámico, debes completar los siguientes pasos:
Implemente un punto final HTTPS.
Sube una clave pública empresarial para el cifrado.
Crea el flujo con la URI de tu punto final.
Adjunta tu Meta app para solicitar la verificación.
Publica el flujo.
Paso 1: Implemente un punto final HTTPS
Su punto final debe cumplir los siguientes requisitos:
URL HTTPS de acceso público con un certificado TLS válido.
Responde en 10 segundos. Meta impone un tiempo de espera máximo y monitorea la latencia de p90. Los terminales que superen constantemente el umbral de latencia o que devuelvan errores pueden verse limitados o bloqueados.
Acepta solicitudes POST que contienen cargas útiles JSON cifradas.
Devuelve las respuestas cifradas como
text/plain(codificadas en base64).
Puedes usar cualquier opción de procesamiento que proporcione una URL HTTPS pública. Entre los enfoques comunes se incluyen los siguientes:
AWS Lambda URL de la función: una función única con un punto final HTTPS incorporado. Establezca el tipo de autorización como
NONEporque Meta no la usa. Las solicitudes se autentican con el par de claves de cifrado empresarial con el que se configuran. Paso 2: Sube una clave pública empresarialAmazon API Gateway con Lambda: proporciona controles adicionales, como políticas de recursos para restringir las IP de origen, AWS WAF las reglas y la limitación.
Objetivos de Elastic Load Balancing con Lambda: resulta útil cuando se desea combinarlos con una infraestructura de equilibrio de carga existente.
Cualquier otro servidor HTTPS (contenedores, instancias de Amazon EC2 o servicios externos).
Su punto final debe implementar el contrato de intercambio de datos de Meta, que gestiona los siguientes tipos de solicitudes:
Control de estado: Meta envía
pingsolicitudes periódicas para verificar que tu terminal esté disponible. Responda con{"data": {"status": "active"}}.INIT: se envía cuando un usuario abre el Flow. Devuelve la pantalla inicial y sus datos.
data_exchange: se envía cada vez que un usuario envía una pantalla. Devuelve la siguiente pantalla y sus datos.
ATRÁS: se envía cuando un usuario vuelve a una pantalla anterior.
Para ver la guía completa de implementación de terminales, que incluye ejemplos de códigos de cifrado y descifrado en varios idiomas, consulta Cómo implementar tu punto final de Flow
Paso 2: Sube una clave pública empresarial
Meta cifra todas las solicitudes de intercambio de datos de principio a fin utilizando su clave pública RSA (Rivest-Shamir-Adleman). Su terminal descifra las solicitudes con la clave privada correspondiente. AWS End User Messaging Social sube la clave pública a Meta en tu nombre, pero nunca accede a la clave privada ni la almacena.
Usa la PutWhatsAppBusinessPublicKey API para subir una clave pública para un número de teléfono. Debes proporcionar exactamente una de las siguientes opciones:
PEM-encoded Clave pública RSA: proporcione la clave directamente. Su terminal contiene la clave privada correspondiente para el descifrado.
AWS Key Management Service clave ARN: proporcione el ARN de una clave de KMS asimétrica RSA-2048 . AWS End User Messaging Social lee solo la parte pública que la usa
kms:GetPublicKeyy la sube a Meta. La clave privada nunca desaparece. AWS KMS Su terminal la utilizakms:Decryptpara descifrar las solicitudes en tiempo de ejecución.
Si proporciona ambos o ninguno, se devuelve unInvalidParametersException.
Modo PEM
Genere un par de claves RSA y cargue la clave pública:
# Generate a key pair openssl genrsa -out private.pem 2048 openssl rsa -in private.pem -pubout -out public.pem # Upload the public key aws social-messaging put-whatsapp-business-public-key \ --origination-phone-number-id{PHONE_NUMBER_ID}\ --business-public-key "$(cat public.pem)"
Almacene la clave privada de forma segura y póngala a disposición de su terminal para que la descifre.
AWS KMS mode
Cree una clave RSA KMS asimétrica y cargue su ARN:
# Create the KMS key KMS_KEY_ARN=$(aws kms create-key \ --key-spec RSA_2048 \ --key-usage ENCRYPT_DECRYPT \ --description "WhatsApp Dynamic Flow encryption key" \ --query KeyMetadata.Arn --output text) # Upload the KMS key ARN aws social-messaging put-whatsapp-business-public-key \ --origination-phone-number-id{PHONE_NUMBER_ID}\ --kms-key-arn$KMS_KEY_ARN
La política de claves de KMS debe conceder los siguientes permisos:
kms:GetPublicKeyal principal delsocial-messaging.amazonaws.com.rproxy.govskope.caservicio. Esto permite a AWS End User Messaging Social leer la clave pública y subirla a Meta.kms:Decrypta la función de ejecución de su terminal. Esto permite que su terminal descifre las solicitudes de intercambio de datos entrantes. AWS End User Messaging Social nunca utiliza estakms:Decryptclave.
Verificación de la clave
Usa la GetWhatsAppBusinessPublicKey API para verificar la clave almacenada y comprobar el estado de firma de Meta:
aws social-messaging get-whatsapp-business-public-key \ --origination-phone-number-id{PHONE_NUMBER_ID}
La respuesta incluye el PEM almacenado y el estado de firma de Meta (VALIDoMISMATCH). Un MISMATCH estado indica que la clave almacenada no coincide con lo que Meta esperaba. Sube una nueva clave si ves este estado.
Paso 3: Crea el flujo con un punto final
Al crear un flujo dinámico, proporcione el --endpoint-uri parámetro junto con la URL de su punto de enlace HTTPS. El JSON de Flow también debe declararsedata_api_version, lo que indica a Meta que llame a tu punto final durante las sesiones de Flow.
aws social-messaging create-whatsapp-flow \ --id{WABA_ID}\ --flow-name "my_dynamic_flow" \ --categories '["OTHER"]' \ --flow-json fileb://flow.json\ --endpoint-uri "https://your-endpoint.example.com/flow"
También puedes añadir o cambiar el punto final de un DRAFT Flow existente medianteUpdateWhatsAppFlow:
aws social-messaging update-whatsapp-flow \ --id{WABA_ID}\ --flow-id{FLOW_ID}\ --endpoint-uri "https://your-endpoint.example.com/flow"
nota
Cuando publicas un flujo dinámico, Meta realiza una comprobación sincrónica del estado de tu punto final. Si el punto final no responde o muestra un error, la operación de publicación falla y se produce un metaerror como 131000 («verifica que el punto final esté disponible y que has implementado una verificación de estado»). La falta de una clave pública empresarial o no válida también puede provocar este error. Antes de publicar, asegúrese de que su terminal esté desplegado y responda a ping las solicitudes, y de que haya subido una clave pública empresarial válida (consultePaso 2: Sube una clave pública empresarial).
Para verificar la versión de la API de datos y puntos finales configurada para un Flow, usaGetWhatsAppFlow:
aws social-messaging get-whatsapp-flow \ --id{WABA_ID}\ --flow-id{FLOW_ID}
La respuesta incluye endpointUri lo que Meta contiene, lo dataApiVersion declarado en el JSON de Flow y lo que está adjunto actualmenteapplication.
Paso 4: Adjunta tu Meta app para solicitar la verificación
De forma predeterminada, cuando creas una red social de mensajería fluida para usuarios AWS finales, esta se asocia a la metaaplicación del servicio. Para comprobar que las solicitudes de intercambio de datos a tu terminal provienen de Meta, adjunta tu propia Meta app a la Flow. Sin tu propia aplicación adjunta, no es posible verificar el origen de la solicitud. Al adjuntar tu aplicación, tendrás acceso al secreto de la aplicación necesario para verificar el encabezado X-Hub-Signature-256 HMAC que Meta incluye en cada solicitud.
aws social-messaging update-whatsapp-flow \ --id{WABA_ID}\ --flow-id{FLOW_ID}\ --meta-app-id "{YOUR_META_APP_ID}"
La aplicación Meta debe ser propiedad de la misma empresa propietaria de la cuenta WhatsApp empresarial (WABA).
importante
Adjuntar tu propia Meta app es una operación unidireccional. Después de adjuntar la aplicación, la aplicación del servicio no se puede volver a conectar. Esto no afecta a la funcionalidad de Flow. Solo un Flow nuevo restablece la asociación de la aplicación.
Puedes configurar --endpoint-uri y hacer --meta-app-id la misma llamada o en llamadas distintas. Los dos campos son independientes.
Después de adjuntar la aplicación, verifica la configuración llamando GetWhatsAppFlow y marcando el application campo de la respuesta. application.idDebe coincidir con el ID de la metaaplicación que proporcionaste.
Proteger su punto final
Dado que Meta llama directamente a su punto final, tenga en cuenta las siguientes prácticas de seguridad:
-
Verifica las firmas de las solicitudes: si has adjuntado tu propia metaaplicación (paso 4), usa el secreto de la aplicación para verificar el
X-Hub-Signature-256HMAC-SHA256 encabezado de cada solicitud. Esto confirma que la solicitud se originó en Meta. Devuelve el estado HTTP 432 si la verificación falla. -
Valida los tokens de flujo: genera un token único e impredecible
flow_tokenpara cada sesión de Flow al enviar el Flow a un usuario. El punto final recibe el token dentro de la carga cifrada y debe validarlo comparándolo con las sesiones activas. Rechaza las solicitudes con tokens desconocidos, caducados o ya completados. Esto evita que las solicitudes no autorizadas o reproducidas lleguen a su lógica empresarial. -
Realice las comprobaciones de estado sin necesidad de realizar una validación simbólica: Meta envía
pingsolicitudes periódicas para supervisar el estado de los terminales. Estas solicitudes no contienen unflow_token. Responda a las comprobaciones de estado sin requerir la validación de un token, ya que rechazarlas reduce la puntuación de disponibilidad de su terminal. -
Devuelve los códigos de estado correspondientes: devuelve el número 421 si tu terminal no puede descifrar la solicitud (Meta recupera la clave pública y lo vuelve a intentar). Devuelve 427 si no
flow_tokenes válido (Meta desactiva el botón Flow de esa sesión).
Escribir un JSON de flujo dinámico
Un JSON de flujo dinámico se diferencia de un JSON de flujo estático en dos aspectos:
El
data_api_versioncampo de nivel superior es obligatorio. Esto le indica a Meta que llame a tu punto final durante las sesiones de Flow. Los valores admitidos son"3.0"y"4.0"(recomendado).Los pies de pantalla utilizan la
data_exchangeacción en lugar denavigate. Cadadata_exchangeacción envía los datos del formulario al punto final, que devuelve la siguiente pantalla y su contenido.
El siguiente ejemplo muestra un JSON de flujo dinámico mínimo con dos pantallas. La primera pantalla recopila el nombre de un usuario y lo envía al punto final. El terminal devuelve un saludo personalizado en la segunda pantalla.
{ "version": "6.0", "data_api_version": "3.0", "routing_model": { "INPUT": ["RESULT"], "RESULT": [] }, "screens": [ { "id": "INPUT", "title": "Welcome", "data": { "greeting": { "type": "string", "__example__": "Tell us your name" } }, "layout": { "type": "SingleColumnLayout", "children": [ { "type": "TextBody", "text": "${data.greeting}" }, { "type": "Form", "name": "input_form", "children": [ { "type": "TextInput", "name": "user_name", "label": "Your name", "input-type": "text", "required": true }, { "type": "Footer", "label": "Submit", "on-click-action": { "name": "data_exchange", "payload": { "user_name": "${form.user_name}" } } } ] } ] } }, { "id": "RESULT", "title": "Hello", "terminal": true, "data": { "message": { "type": "string", "__example__": "Hello, World!" } }, "layout": { "type": "SingleColumnLayout", "children": [ { "type": "TextBody", "text": "${data.message}" }, { "type": "Footer", "label": "Done", "on-click-action": { "name": "complete", "payload": {} } } ] } } ] }
Para ver la referencia completa del esquema JSON de Flow, consulta Flow JSON
End-to-end ejemplo
El siguiente ejemplo muestra la secuencia completa de llamadas a la API para configurar y publicar un flujo dinámico:
# 1. Upload the business public key (KMS mode) aws social-messaging put-whatsapp-business-public-key \ --origination-phone-number-id{PHONE_NUMBER_ID}\ --kms-key-arn{KMS_KEY_ARN}# 2. Create the Dynamic Flow with an endpoint FLOW_ID=$(aws social-messaging create-whatsapp-flow \ --id{WABA_ID}\ --flow-name "my_dynamic_flow" \ --categories '["OTHER"]' \ --flow-json fileb://flow.json\ --endpoint-uri "https://your-endpoint.example.com/flow" \ --query flowId --output text) # 3. Attach your Meta app for signature verification aws social-messaging update-whatsapp-flow \ --id{WABA_ID}\ --flow-id $FLOW_ID \ --meta-app-id "{YOUR_META_APP_ID}" # 4. Publish the Flow aws social-messaging publish-whatsapp-flow \ --id{WABA_ID}\ --flow-id $FLOW_ID # 5. Verify the configuration aws social-messaging get-whatsapp-flow \ --id{WABA_ID}\ --flow-id $FLOW_ID
Tras la publicación, el flujo está disponible para su uso en los mensajes de plantilla. Para obtener más información sobre el envío de flujos, consulteEnvío de WhatsApp flujos a los usuarios.
