DEV Community: ensamblador

Respondiendo DMs de X en Amazon Connect Chat

ensamblador — Fri, 03 Apr 2026 17:11:39 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Aprende cómo conectar los Mensajes Directos de X (Twitter) con Amazon Connect Chat para una atención al cliente fluida. Esta guía paso a paso cubre la arquitectura completa usando AWS CDK, AWS Lambda, Amazon API Gateway, Amazon DynamoDB y Amazon Connect. Desde recibir DMs de clientes hasta enrutarlos a agentes, reenviar respuestas de agentes a X y manejar archivos adjuntos en ambas direcciones — todo con gestión automática de sesiones, validación CRC de webhooks y caché de perfiles de usuario vía el SDK de Tweepy.

Tus clientes ya están en X. Siguen tu marca, interactúan con tus publicaciones, y cuando necesitan ayuda — envían un DM. Si tu equipo de soporte tiene que alternar entre X y su herramienta de contact center, estás perdiendo tiempo y contexto.

En este blog, aprenderás cómo conectar los Mensajes Directos de X directamente a Amazon Connect Chat, para que tus agentes manejen conversaciones de X desde el mismo workspace que usan para todos los demás canales. Sin cambiar de app, sin copiar y pegar, sin mensajes perdidos.

Revisa el código en Github

Qué vas a construir

Un puente de mensajería bidireccional entre DMs de X y Amazon Connect que:

Recibe DMs entrantes de X vía el webhook del Account Activity API y los enruta a Amazon Connect Chat
Reenvía las respuestas de los agentes desde Amazon Connect de vuelta a X a través del SDK de Tweepy
Gestiona sesiones de chat automáticamente — creando nuevas, reutilizando activas y limpiando las expiradas
Cachea perfiles de usuario de X (nombre, username, imagen de perfil) en DynamoDB para reducir llamadas al API
Maneja archivos adjuntos en ambas direcciones — imágenes, videos y GIFs de clientes, e imágenes y videos de agentes
Previene loops echo filtrando mensajes enviados por tu propia cuenta de X

El resultado final: los agentes ven las conversaciones de X como contactos de chat regulares en su workspace de Amazon Connect, con el nombre y la información de perfil del cliente.

Arquitectura

Así funciona el flujo:

Un cliente envía un DM en X. El Account Activity API entrega el evento webhook a un endpoint de API Gateway
La Lambda del Inbound Handler valida el webhook (CRC challenge), parsea el mensaje y busca o crea una sesión de Amazon Connect Chat
El perfil de X del cliente (si no está presente en el request) se obtiene vía el SDK de Tweepy y se cachea en DynamoDB
Los mensajes de texto y archivos adjuntos se envían a la sesión de Connect Chat vía el Participant API
Cuando un agente responde, Amazon Connect publica el evento a un topic SNS vía contact streaming
La Lambda del Outbound Handler recibe el evento SNS, busca el ID de usuario de X del cliente y envía la respuesta como DM a través del SDK de Tweepy

Entrante: X → Amazon Connect

Cuando un cliente envía un DM a tu cuenta business de X, el flujo entrante maneja todo, desde la validación del webhook hasta la entrega del mensaje.

1. Validación CRC del Webhook

X usa un Challenge-Response Check (CRC) para verificar la propiedad del webhook — esto es fundamentalmente diferente del enfoque de Meta usado en las integraciones de Instagram y Facebook Messenger. En lugar de comparar un string secreto compartido, X envía un crc_token que debe ser hasheado con tu Consumer Secret usando HMAC-SHA256:

def compute_crc_response(crc_token, consumer_secret):
    digest = hmac.new(
        consumer_secret.encode('utf-8'),
        crc_token.encode('utf-8'),
        hashlib.sha256
    ).digest()

    encoded_hash = base64.b64encode(digest).decode('utf-8')
    return {"response_token": f"sha256={encoded_hash}"}

X envía este challenge tanto durante el registro inicial del webhook como periódicamente después para re-validar. La Lambda lo maneja automáticamente en cada solicitud GET.

2. Parseo de Mensajes y Prevención de Echo

Para solicitudes POST (eventos DM reales), la clase XService parsea el payload direct_message_events. Cada evento contiene el ID del remitente, ID del destinatario, contenido de texto y cualquier adjunto multimedia:

class XMessage:
    def __init__(self, event_data):
        message_create = event_data.get('message_create', {})
        message_data = message_create.get('message_data', {})
        self.sender_id = message_create.get('sender_id')
        self.text = message_data.get('text')
        self.recipient_id = message_create.get('target', {}).get('recipient_id')

        # Parsear adjunto si está presente
        self.attachment = message_data.get('attachment')
        if self.attachment and self.attachment.get('type') == 'media':
            media = self.attachment.get('media', {})
            self.attachment_url = media.get('media_url_https')
            self.attachment_type = media.get('type')  # photo, animated_gif, video

El servicio filtra mensajes enviados por tu propio ID de cuenta de X para prevenir loops echo — cuando tu cuenta envía una respuesta, X también la entrega como evento webhook.

3. Obtención y Caché de Perfiles de Usuario

Los payloads del webhook de X incluyen datos de perfil de usuario inline en un diccionario users, que el servicio extrae primero. Para perfiles faltantes, recurre a una búsqueda de tres niveles:

def get_user_profile(self, user_id):
    # Verificar caché en memoria primero
    if user_id in self.user_profiles:
        return self.user_profiles[user_id]

    # Verificar tabla de usuarios en DynamoDB
    if USERS_TABLE_NAME:
        users_table = TableService(table_name=USERS_TABLE_NAME)
        db_profile = users_table.get_item({"id": user_id})
        if db_profile:
            return db_profile

    # Obtener del X API vía Tweepy como último recurso
    client = tweepy.Client(
        consumer_key=credentials.get('consumer_key'),
        consumer_secret=credentials.get('consumer_secret'),
        access_token=credentials.get('access_token'),
        access_token_secret=credentials.get('access_token_secret')
    )
    response = client.get_user(id=user_id, user_fields=['name', 'username', 'profile_image_url'])
    # ... cachear en DynamoDB con TTL de 7 días

El perfil incluye name, username y profile_image_url. Los perfiles se cachean en una tabla DynamoDB con un TTL de 7 días, así que las conversaciones repetidas se saltan la llamada al API.

4. Gestión de Sesiones

El handler verifica en DynamoDB si existe una sesión de chat activa usando el ID de usuario de X del remitente:

Si existe una sesión, envía el mensaje usando el connectionToken almacenado. Si el token expiró (AccessDeniedException), crea automáticamente una nueva sesión.
Si no existe sesión, llama a StartChatContact para crear un nuevo Amazon Connect Chat, inicia contact streaming al topic SNS, crea una conexión de participante y almacena todo en DynamoDB.

Los atributos de contacto incluyen el nombre del canal ("X"), el ID del cliente y el nombre de display del cliente — facilitando identificar el canal de origen en Contact Flows y enrutamiento de agentes.

5. Manejo de Archivos Adjuntos (Entrante)

Cuando un cliente envía una imagen, GIF o video, el handler lo descarga del CDN de X y lo sube a la sesión de Connect Chat. Las URLs de media de X vienen en dos variantes:

pbs.twimg.com — accesible públicamente, descarga directa
ton.twitter.com — requiere autenticación OAuth 1.0a (usando requests_oauthlib)

La carga usa el flujo de tres pasos del Participant API: start_attachment_upload → PUT a URL pre-firmada → complete_attachment_upload. Si algo falla, el handler envía la URL del media como mensaje de texto.

Para adjuntos que incluyen un caption, el texto se limpia eliminando el enlace t.co que X agrega automáticamente al cuerpo del mensaje.

Saliente: Amazon Connect → X

Cuando un agente responde desde el workspace de Amazon Connect, el flujo saliente entrega el mensaje de vuelta a X.

1. Eventos de Streaming vía SNS

Amazon Connect publica eventos de streaming de chat a un topic SNS. La Lambda del Outbound Handler se suscribe a este topic y procesa tres tipos de eventos:

MESSAGE — mensajes de texto del agente
ATTACHMENT — archivos adjuntos enviados por el agente
EVENT — eventos de unión/salida de participantes y fin de chat

Los mensajes del rol CUSTOMER se omiten para evitar procesar los propios mensajes del cliente nuevamente.

2. Envío de Mensajes de Texto

Para mensajes de texto con visibilidad CUSTOMER o ALL, el handler busca el ID de usuario de X del cliente en DynamoDB y envía la respuesta vía el API v2 de Tweepy:

def send_x_text(credentials, text, recipient_id):
    client = tweepy.Client(
        consumer_key=credentials["consumer_key"],
        consumer_secret=credentials["consumer_secret"],
        access_token=credentials["access_token"],
        access_token_secret=credentials["access_token_secret"],
    )
    response = client.create_direct_message(
        participant_id=recipient_id,
        text=text,
    )
    return response

3. Envío de Archivos Adjuntos

Cuando un agente envía un archivo desde el widget de Connect Chat, el handler obtiene una URL firmada del adjunto, lo descarga y lo sube a X vía el endpoint de media upload v1.1 (OAuth 1.0a). El media ID se usa luego para enviar un DM con el adjunto:

Tipo MIME	Categoría de media X	Método de carga
`image/jpeg`, `image/png`, `image/webp`	`dm_image`	`media_upload`
`image/gif`	`dm_gif`	`chunked_upload`
`video/mp4`	`dm_video`	`chunked_upload`
todo lo demás	—	Enviado como enlace de texto

Los DMs de X solo soportan imágenes y videos como media nativo. Los tipos no soportados (PDFs, documentos, etc.) se envían como URLs en texto plano para que el cliente aún tenga acceso al contenido.

4. Limpieza de Sesiones

Cuando un participante sale o el chat termina, el handler elimina el registro de conexión de DynamoDB para que el próximo mensaje entrante inicie una sesión nueva.

Tipos de Mensajes Soportados

Dirección	Texto	Imágenes	Videos	GIFs
Entrante (cliente → agente)	✅	✅	✅	✅
Saliente (agente → cliente)	✅	✅	✅	✅

Los tipos de media no soportados (PDFs, documentos, etc.) se envían como enlaces de texto plano en la dirección saliente.

Qué se Despliega

Recurso	Servicio	Propósito
Endpoint `/webhooks` (GET & POST)	API Gateway	Recibe desafíos CRC de X (GET) y eventos DM entrantes (POST)
Inbound Handler	Lambda	Procesa eventos DM de X y los enruta a Amazon Connect Chat
Outbound Handler	Lambda	Envía respuestas de agentes de vuelta a X como DMs vía el SDK de Tweepy
Tabla Active Connections	DynamoDB	Rastrea sesiones de chat abiertas (`contactId` PK, `userId` GSI)
Tabla X Users	DynamoDB	Cachea perfiles de usuario de X (expiración por TTL, 7 días)
Topic `messages_out`	SNS	Entrega eventos de streaming de Amazon Connect al Outbound Handler
`x-dm-credentials`	Secrets Manager	Almacena credenciales OAuth 1.0a del X API (Consumer Key, Consumer Secret, Access Token, Access Token Secret)
`/x/dm/config`	SSM Parameter Store	Contiene instance ID de Connect, contact flow ID e ID de cuenta de X
`/x/dm/webhook/url`	SSM Parameter Store	Almacena la URL del callback de API Gateway desplegado

Estimación de Costos

Escenario de ejemplo: 1,000 conversaciones por mes, promediando 10 mensajes cada una (5 entrantes + 5 salientes), totalizando 10,000 mensajes.

Componente	Costo Mensual Estimado	Notas
Infraestructura (API GW, Lambda, DynamoDB, SNS, Secrets Manager)	~$0.71	Despreciable a esta escala
Amazon Connect Chat (Entrante)	$20.00	5,000 msgs × $0.004/msg
Amazon Connect Chat (Saliente)	$20.00	5,000 msgs × $0.004/msg
X API — DMs Salientes	~$50.00	5,000 envíos de DM × ~$0.01/request
Total	~$90.71

El X API usa precios de pago por uso basados en créditos. El costo por endpoint mostrado arriba es aproximado — las tarifas reales se muestran en la Consola de Desarrollador de X y pueden cambiar. Consulta los precios de Amazon Connect y los precios del X API para tarifas actuales.

Para reducir costos de Connect Chat en conversaciones de alto volumen, considera agregar una capa de buffering de mensajes para agregar mensajes consecutivos rápidos.

Prerrequisitos de Despliegue

Antes de comenzar necesitarás:

Cuenta de Desarrollador de X y Credenciales API

Necesitas una cuenta de desarrollador de X con al menos el tier Pay-Per-Use, y cuatro credenciales OAuth 1.0a (Consumer Key, Consumer Secret, Access Token, Access Token Secret).

Consulta la Guía de Configuración de X para instrucciones detalladas paso a paso sobre cómo crear tu app, configurar permisos y generar credenciales.

⚠️ Importante: El tier gratuito no incluye entrega de DMs basada en webhooks. Necesitas el tier Pay-Per-Use.

Una Instancia de Amazon Connect

Necesitas una instancia de Amazon Connect. Si aún no tienes una, puedes seguir esta guía para crear una.

Necesitarás el INSTANCE_ID de tu instancia. Lo puedes encontrar en la consola de Amazon Connect o en el ARN de la instancia:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

Un Flujo de Chat para Manejar Mensajes

Crea o ten listo el flujo de contacto que define la experiencia del usuario. Sigue esta guía para crear un Inbound Contact Flow. El más sencillo funcionará.

Recuerda publicar el flujo.

Toma nota del INSTANCE_ID y CONTACT_FLOW_ID en la pestaña de Detalles. Los valores están en el ARN del flujo:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(consulta los Prerrequisitos de Amazon Connect para más detalles)

Despliegue con AWS CDK

⚠️ Despliega en la misma región donde tu instancia de Amazon Connect está configurada.

1. Clona el repositorio y navega al proyecto

git clone https://github.com/aws-samples/sample-amazon-connect-social-integration.git
cd sample-amazon-connect-social-integration/x-dm-connect-chat

2. Despliega con CDK

Sigue las instrucciones en la Guía de Despliegue CDK para configuración del entorno y comandos de despliegue.

Configuración Post-despliegue

Después del despliegue, se necesitan tres pasos de configuración:

Actualizar Credenciales del X API — El stack crea un secreto en Secrets Manager llamado x-dm-credentials con valores placeholder. Actualízalo con tu Consumer Key, Consumer Secret, Access Token y Access Token Secret reales.
Actualizar Configuración SSM — Actualiza el parámetro SSM /x/dm/config con tu instance_id de Amazon Connect, contact_flow_id y el x_account_id numérico de tu cuenta de X.
Registrar el Webhook y Suscribirse — Registra la URL de tu API Gateway desplegado con el Account Activity API de X y suscribe tu cuenta business para recibir eventos DM. El Inbound Handler responde a los desafíos CRC automáticamente.

Para instrucciones detalladas de cada paso, incluyendo cómo encontrar tu x_account_id y registrar el webhook, consulta el README del proyecto y la Guía de Configuración de X.

Pruebas

Ve a tu instancia de Amazon Connect y abre el Contact Control Panel (CCP).

Prueba estos escenarios:

Envía un DM a tu cuenta business de X desde otra cuenta de X — debería aparecer como un nuevo contacto de chat en el CCP
Responde desde el CCP — la respuesta debería llegar a los DMs de X del cliente
Envía una imagen desde X — debería aparecer como un adjunto de imagen en el chat del agente
Desde el lado del agente, envía una imagen — debería aparecer en los DMs de X del cliente
Intenta enviar un documento desde el lado del agente — debería llegar como enlace en los DMs del cliente

Consideraciones Importantes sobre X

DMs Encriptados

X soporta Mensajes Directos con encriptación de extremo a extremo (E2EE). Sin embargo, los DMs encriptados no son accesibles vía el X API. Esta integración solo procesa DMs estándar (no encriptados). Si una conversación está encriptada, el webhook no recibirá esos eventos de mensaje.

Tier Pay-Per-Use

El tier Pay-Per-Use es requerido para acceso al Account Activity API. El tier gratuito no incluye entrega de DMs basada en webhooks.
Revisa los precios del X API para detalles y costos actuales.

Re-validación CRC

X periódicamente re-envía desafíos CRC para verificar que tu webhook sigue siendo válido. El Inbound Handler maneja esto automáticamente, pero asegúrate de que las credenciales en Secrets Manager permanezcan válidas y la función Lambda siga desplegada.

Credenciales OAuth 1.0a

Las cuatro credenciales (Consumer Key, Consumer Secret, Access Token, Access Token Secret) deben permanecer válidas. Si regeneras cualquier credencial en el Portal de Desarrollador de X, actualiza el secreto en Secrets Manager inmediatamente.
El Access Token y Access Token Secret están vinculados a la cuenta de usuario de X específica que posee la app. Asegúrate de que sea la cuenta business que debe recibir y enviar DMs.

Límites de Tasa

El X API aplica límites de tasa en los endpoints de DM. El Account Activity API tiene sus propios límites en registros de webhooks y validaciones CRC.
Monitorea tu uso en el dashboard del Portal de Desarrollador de X.

Próximos Pasos

Esta solución maneja el flujo principal de mensajería X DM-a-Connect. Algunas ideas para extenderla:

Usar Amazon Bedrock para analizar imágenes entrantes y dar contexto a los agentes antes de que respondan
Usar Amazon Connect AI Agents para autoservicio agéntico, permitiendo a los clientes resolver problemas comunes sin esperar a un agente humano
Combinar con la integración de Instagram DM y la integración de Facebook Messenger para manejar todos los canales sociales desde una sola instancia de Amazon Connect

Aprovechar Amazon Connect Customer Profiles

Esta solución ya obtiene datos del perfil de X (nombre, username, imagen de perfil) y los pasa como atributos de contacto. Puedes ir más allá integrando con Amazon Connect Customer Profiles para dar a los agentes una vista unificada del cliente a través de canales. Luego en tu Contact Flow, usa el bloque Customer Profiles para recuperar el perfil y mostrarlo en el workspace del agente. El agente ve el nombre del cliente, su handle de X y cualquier historial de interacciones previas — todo antes de escribir una respuesta.

Recursos

Answer X DMs in Amazon Connect Chat

ensamblador — Fri, 03 Apr 2026 17:06:29 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Learn how to bridge X (Twitter) Direct Messages and Amazon Connect Chat for seamless customer service. This step-by-step guide covers the full architecture using AWS CDK, AWS Lambda, Amazon API Gateway, Amazon DynamoDB, and Amazon Connect. From receiving customer DMs to routing them to agents, forwarding agent replies back to X, and handling attachments in both directions — all with automatic session management, CRC webhook validation, and user profile caching via the Tweepy SDK.

Your customers are already on X. They follow your brand, engage with your posts, and when they need help — they send a DM. If your support team has to switch between X and their contact center tool, you're losing time and context.

In this blog, you'll learn how to connect X Direct Messages directly to Amazon Connect Chat, so your agents can handle X conversations from the same workspace they use for every other channel. No app switching, no copy-pasting, no lost messages.

Check out the code at Github

What you'll build

A bidirectional messaging bridge between X DMs and Amazon Connect that:

Receives incoming X DMs via the Account Activity API webhook and routes them to Amazon Connect Chat
Forwards agent replies from Amazon Connect back to X through the Tweepy SDK
Manages chat sessions automatically — creating new ones, reusing active ones, and cleaning up expired ones
Caches X user profiles (name, username, profile image) in DynamoDB to reduce API calls
Handles attachments in both directions — images, videos, and GIFs from customers, and images and videos from agents
Prevents echo loops by filtering out messages sent by your own X account

The end result: agents see X conversations as regular chat contacts in their Amazon Connect workspace, complete with the customer's X display name and profile information.

Architecture

Here's how it flows:

A customer sends a DM on X. The Account Activity API delivers the webhook event to an API Gateway endpoint
The Inbound Handler Lambda validates the webhook (CRC challenge), parses the message, and looks up or creates an Amazon Connect Chat session
The customer's X profile (if not present) is fetched via the Tweepy SDK and cached in DynamoDB
Text messages and attachments are forwarded into the Connect Chat session via the Participant API
When an agent replies, Amazon Connect publishes the event to an SNS topic via contact streaming
The Outbound Handler Lambda picks up the SNS event, looks up the customer's X user ID, and sends the reply back as a DM through the Tweepy SDK

Inbound: X → Amazon Connect

When a customer sends a DM to your business X account, the inbound path handles everything from webhook validation to message delivery.

1. CRC Webhook Validation

X uses a Challenge-Response Check (CRC) to verify webhook ownership — this is fundamentally different from Meta's approach used in the Instagram and Facebook Messenger integrations. Instead of comparing a shared secret string, X sends a crc_token that must be hashed with your Consumer Secret using HMAC-SHA256:

def compute_crc_response(crc_token, consumer_secret):
    digest = hmac.new(
        consumer_secret.encode('utf-8'),
        crc_token.encode('utf-8'),
        hashlib.sha256
    ).digest()

    encoded_hash = base64.b64encode(digest).decode('utf-8')
    return {"response_token": f"sha256={encoded_hash}"}

X sends this challenge both during initial webhook registration and periodically afterward to re-validate. The Lambda handles it automatically on every GET request.

2. Message Parsing and Echo Prevention

For POST requests (actual DM events), the XService class parses the direct_message_events payload. Each event contains the sender ID, recipient ID, text content, and any media attachments:

class XMessage:
    def __init__(self, event_data):
        message_create = event_data.get('message_create', {})
        message_data = message_create.get('message_data', {})
        self.sender_id = message_create.get('sender_id')
        self.text = message_data.get('text')
        self.recipient_id = message_create.get('target', {}).get('recipient_id')

        # Parse attachment if present
        self.attachment = message_data.get('attachment')
        if self.attachment and self.attachment.get('type') == 'media':
            media = self.attachment.get('media', {})
            self.attachment_url = media.get('media_url_https')
            self.attachment_type = media.get('type')  # photo, animated_gif, video

The service filters out messages sent by your own X account ID to prevent echo loops — when your account sends a reply, X also delivers it as a webhook event.

3. User Profile Retrieval and Caching

X webhook payloads include inline user profile data in a users dictionary, which the service extracts first. For any missing profiles, it falls back to a three-tier lookup:

def get_user_profile(self, user_id):
    # Check in-memory cache first
    if user_id in self.user_profiles:
        return self.user_profiles[user_id]

    # Check DynamoDB users table
    if USERS_TABLE_NAME:
        users_table = TableService(table_name=USERS_TABLE_NAME)
        db_profile = users_table.get_item({"id": user_id})
        if db_profile:
            return db_profile

    # Fetch from X API via Tweepy as last resort
    client = tweepy.Client(
        consumer_key=credentials.get('consumer_key'),
        consumer_secret=credentials.get('consumer_secret'),
        access_token=credentials.get('access_token'),
        access_token_secret=credentials.get('access_token_secret')
    )
    response = client.get_user(id=user_id, user_fields=['name', 'username', 'profile_image_url'])
    # ... cache in DynamoDB with 7-day TTL

The profile includes name, username, and profile_image_url. Profiles are cached in a DynamoDB table with a 7-day TTL, so repeat conversations skip the API call entirely.

4. Session Management

The handler checks DynamoDB for an existing chat session using the sender's X user ID:

If a session exists, it sends the message using the stored connectionToken. If the token is expired (AccessDeniedException), it automatically creates a new session.
If no session exists, it calls StartChatContact to create a new Amazon Connect Chat, starts contact streaming to the SNS topic, creates a participant connection, and stores everything in DynamoDB.

The contact attributes include the channel name ("X"), the customer ID, and the customer's display name — making it easy to identify the source channel in Contact Flows and agent routing.

5. Attachment Handling (Inbound)

When a customer sends an image, GIF, or video, the handler downloads it from X's CDN and uploads it to the Connect Chat session. X media URLs come in two flavors:

pbs.twimg.com — publicly accessible, downloaded directly
ton.twitter.com — requires OAuth 1.0a authentication (using requests_oauthlib)

The upload uses the three-step Participant API flow: start_attachment_upload → PUT to pre-signed URL → complete_attachment_upload. If anything fails, the handler falls back to sending the media URL as a text message.

For attachments that include a caption, the text is cleaned up by stripping the auto-appended t.co media link that X adds to the message body.

Outbound: Amazon Connect → X

When an agent replies from the Amazon Connect workspace, the outbound path delivers the message back to X.

1. Streaming Events via SNS

Amazon Connect publishes chat streaming events to an SNS topic. The Outbound Handler Lambda subscribes to this topic and processes three event types:

MESSAGE — text messages from the agent
ATTACHMENT — file attachments sent by the agent
EVENT — participant join/leave and chat ended events

Messages from the CUSTOMER role are skipped to avoid processing the customer's own messages again.

2. Sending Text Messages

For text messages with CUSTOMER or ALL visibility, the handler looks up the customer's X user ID from DynamoDB and sends the reply via the Tweepy v2 API:

def send_x_text(credentials, text, recipient_id):
    client = tweepy.Client(
        consumer_key=credentials["consumer_key"],
        consumer_secret=credentials["consumer_secret"],
        access_token=credentials["access_token"],
        access_token_secret=credentials["access_token_secret"],
    )
    response = client.create_direct_message(
        participant_id=recipient_id,
        text=text,
    )
    return response

3. Sending Attachments

When an agent sends a file from the Connect Chat widget, the handler retrieves a signed URL for the attachment, downloads it, and uploads it to X via the v1.1 media upload endpoint (OAuth 1.0a). The media ID is then used to send a DM with the attachment:

MIME type	X media category	Upload method
`image/jpeg`, `image/png`, `image/webp`	`dm_image`	`media_upload`
`image/gif`	`dm_gif`	`chunked_upload`
`video/mp4`	`dm_video`	`chunked_upload`
everything else	—	Sent as plain-text link

X DMs only support images and videos as native media. Unsupported types (PDFs, documents, etc.) are sent as plain-text URLs so the customer still has access to the content.

4. Session Cleanup

When a participant leaves or the chat ends, the handler deletes the connection record from DynamoDB so the next inbound message starts a fresh session.

Message Types Supported

Direction	Text	Images	Videos	GIFs
Inbound (customer → agent)	✅	✅	✅	✅
Outbound (agent → customer)	✅	✅	✅	✅

Unsupported media types (PDFs, documents, etc.) are sent as plain-text links in the outbound direction.

What Gets Deployed

Resource	Service	Purpose
`/webhooks` endpoint (GET & POST)	API Gateway	Receives X CRC challenges (GET) and inbound DM events (POST)
Inbound Handler	Lambda	Processes X DM events and routes them to Amazon Connect Chat
Outbound Handler	Lambda	Sends agent replies back to X as DMs via the Tweepy SDK
Active Connections table	DynamoDB	Tracks open chat sessions (`contactId` PK, `userId` GSI)
X Users table	DynamoDB	Caches X user profiles (TTL-based expiry, 7 days)
`messages_out` topic	SNS	Delivers Amazon Connect streaming events to the Outbound Handler
`x-dm-credentials`	Secrets Manager	Stores X API OAuth 1.0a credentials (Consumer Key, Consumer Secret, Access Token, Access Token Secret)
`/x/dm/config`	SSM Parameter Store	Holds Connect instance ID, contact flow ID, and X account ID
`/x/dm/webhook/url`	SSM Parameter Store	Stores the deployed API Gateway callback URL

Cost Estimation

Example scenario: 1,000 conversations per month, averaging 10 messages each (5 inbound + 5 outbound), totaling 10,000 messages.

Component	Estimated Monthly Cost	Notes
Infrastructure (API GW, Lambda, DynamoDB, SNS, Secrets Manager)	~$0.71	Negligible at this scale
Amazon Connect Chat (Inbound)	$20.00	5,000 msgs × $0.004/msg
Amazon Connect Chat (Outbound)	$20.00	5,000 msgs × $0.004/msg
X API — Outbound DMs	~$50.00	5,000 DM sends × ~$0.01/request
Total	~$90.71

X API uses credit-based pay-per-use pricing. The per-endpoint cost shown above is approximate — actual rates are displayed in the X Developer Console and may change. See Amazon Connect pricing and X API pricing for current rates.

To reduce Connect Chat costs on high-volume conversations, consider adding a message buffering layer to aggregate rapid consecutive messages.

Deployment Prerequisites

Before getting started you'll need:

X Developer Account and API Credentials

You need an X Developer Account with at least the Pay-Per-Use tier, and four OAuth 1.0a credentials (Consumer Key, Consumer Secret, Access Token, Access Token Secret).

See the X Platform Setup Guide for detailed step-by-step instructions on creating your app, configuring permissions, and generating credentials.

⚠️ Important: The free tier does not include webhook-based DM delivery. You need the Pay-Per-Use tier.

An Amazon Connect Instance

You need an Amazon Connect instance. If you don't have one yet, you can follow this guide to create one.

You'll need the INSTANCE_ID of your instance. You can find it in the Amazon Connect console or in the instance ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

A Chat Flow to Handle Messages

Create or have ready the contact flow that defines the user experience. Follow this guide to create an Inbound Contact Flow. The simplest one will work.

Remember to publish the flow.

Take note of the INSTANCE_ID and CONTACT_FLOW_ID from the Details tab. The values are in the flow ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(see the Amazon Connect Prerequisites for more details)

Deploying with AWS CDK

⚠️ Deploy in the same region where your Amazon Connect instance is configured.

1. Clone the repository and navigate to the project

git clone https://github.com/aws-samples/sample-amazon-connect-social-integration.git
cd sample-amazon-connect-social-integration/x-dm-connect-chat

2. Deploy with CDK

Follow the instructions in the CDK Deployment Guide for environment setup and deployment commands.

Post-deployment Configuration

After deployment, three configuration steps are needed:

Update X API Credentials — The stack creates a Secrets Manager secret named x-dm-credentials with placeholder values. Update it with your actual Consumer Key, Consumer Secret, Access Token, and Access Token Secret.
Update SSM Configuration — Update the SSM parameter /x/dm/config with your Amazon Connect instance_id, contact_flow_id, and your X account's numeric x_account_id.
Register the Webhook and Subscribe — Register your deployed API Gateway URL with the X Account Activity API and subscribe your business account to receive DM events. The Inbound Handler responds to CRC challenges automatically.

For detailed instructions on each step, including how to find your x_account_id and register the webhook, see the project README and the X Platform Setup Guide.

Testing

Go to your Amazon Connect instance and open the Contact Control Panel (CCP).

Try these scenarios:

Send a DM to your business X account from another X account — it should appear as a new chat contact in the CCP
Reply from the CCP — the response should arrive in the customer's X DMs
Send an image from X — it should appear as an image attachment in the agent's chat
From the agent side, send an image — it should appear in the customer's X DMs
Try sending a document from the agent side — it should arrive as a link in the customer's DMs

Important Considerations around X

Encrypted DMs

X supports end-to-end encrypted (E2EE) Direct Messages. However, encrypted DMs are not accessible via the X API. This integration only processes standard (non-encrypted) DMs. If a conversation is encrypted, the webhook will not receive those message events.

Pay-Per-Use Tier

The Pay-Per-Use tier is required for Account Activity API access. The free tier does not include webhook-based DM delivery.
Review X API pricing for current tier details and costs.

CRC Re-validation

X periodically re-sends CRC challenges to verify your webhook is still valid. The Inbound Handler handles this automatically, but ensure the Secrets Manager credentials remain valid and the Lambda function stays deployed.

OAuth 1.0a Credentials

All four credentials (Consumer Key, Consumer Secret, Access Token, Access Token Secret) must remain valid. If you regenerate any credential in the X Developer Portal, update the Secrets Manager secret immediately.
The Access Token and Access Token Secret are tied to the specific X user account that owns the app. Ensure this is the business account that should receive and send DMs.

Rate Limits

The X API enforces rate limits on DM endpoints. The Account Activity API has its own limits on webhook registrations and CRC validations.
Monitor your usage in the X Developer Portal dashboard.

Next Steps

This solution handles the core X DM-to-Connect messaging flow. Some ideas to extend it:

Use Amazon Bedrock to analyze inbound images and provide agents with context before they respond
Use Amazon Connect AI Agents for agentic self-service, letting customers resolve common issues without waiting for a human agent
Combine with the Instagram DM integration and Facebook Messenger integration to handle all social channels from a single Amazon Connect instance

Leverage Amazon Connect Customer Profiles

This solution already fetches X profile data (name, username, profile image) and passes it as contact attributes. You can take this further by integrating with Amazon Connect Customer Profiles to give agents a unified view of the customer across channels. Then in your Contact Flow, use the Customer Profiles block to retrieve the profile and display it in the agent workspace. The agent sees the customer's name, X handle, and any previous interaction history — all before they even type a reply.

Resources

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Facebook Messenger to Amazon Connect Chat

ensamblador — Wed, 01 Apr 2026 19:00:00 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Learn how to bridge Facebook Messenger and Amazon Connect Chat for seamless customer service. This step-by-step guide covers the full architecture using AWS CDK, AWS Lambda, Amazon API Gateway, Amazon DynamoDB, and Amazon Connect. From receiving customer messages to routing them to agents, forwarding agent replies back to Messenger, and handling attachments in both directions — all with automatic session management and user profile caching via the Graph API.

Facebook Messenger has over a billion active users. Many of them are already messaging your Facebook Page with questions about products, order status, or support requests. If your agents have to juggle between the Meta Business Suite and their contact center, context gets lost and response times suffer.

In this blog, you'll learn how to connect Facebook Messenger directly to Amazon Connect Chat, so your agents handle Messenger conversations from the same workspace they use for every other channel. Messages flow in both directions — including images, documents, and files — with automatic session management and user profile enrichment.

Check out the code at Github

What you'll build

A bidirectional messaging bridge between Facebook Messenger and Amazon Connect that:

Receives incoming Messenger messages via Meta webhooks and routes them to Amazon Connect Chat
Forwards agent replies from Amazon Connect back to Messenger through the Send API
Manages chat sessions automatically — creating new ones, reusing active ones, and cleaning up expired ones
Fetches and caches Messenger user profiles (first name, last name, profile picture) via the Graph API
Handles attachments in both directions — images and files from customers, and images and files from agents
Prevents echo loops by filtering out messages sent by your own Page

The end result: agents see Messenger conversations as regular chat contacts in their Amazon Connect workspace, with the customer's real name displayed.

Architecture

Here's how it flows:

A customer sends a message on Facebook Messenger. Meta delivers the webhook event to an API Gateway endpoint
The Inbound Handler Lambda validates the webhook, parses the message, and looks up or creates an Amazon Connect Chat session
The customer's Messenger profile is fetched via the Graph API and cached in DynamoDB
Text messages and attachments are forwarded into the Connect Chat session via the Participant API
When an agent replies, Amazon Connect publishes the event to an SNS topic via contact streaming
The Outbound Handler Lambda picks up the SNS event, looks up the customer's Page-Scoped ID (PSID), and sends the reply back through the Messenger Send API

Inbound: Messenger → Amazon Connect

When a customer sends a message to your Facebook Page, the inbound path handles everything from webhook validation to message delivery.

1. Webhook Validation and Message Parsing

Meta sends webhook events to your API Gateway /messages endpoint. The Lambda handles GET requests for webhook verification — Meta sends hub.mode, hub.verify_token, and hub.challenge parameters that must be validated and echoed back.

For POST requests, the MessengerService class parses the webhook payload. Messenger webhooks arrive with object: "page" and contain entries with messaging data:

class MessengerMessage:
    def __init__(self, messaging_data):
        self.sender_id = messaging_data.get('sender', {}).get('id')
        self.recipient_id = messaging_data.get('recipient', {}).get('id')
        self.timestamp = messaging_data.get('timestamp')

        message_data = messaging_data.get('message', {})
        self.message_id = message_data.get('mid')
        self.text = message_data.get('text')
        self.attachments = message_data.get('attachments', [])

        if self.text:
            self.message_type = 'text'
        elif len(self.attachments):
            self.message_type = 'attachment'
        else:
            self.message_type = 'unknown'

The service filters out messages sent by your own Page ID to prevent echo loops — when your Page sends a reply, Meta also delivers it as a webhook event, and without this filter you'd get an infinite cycle.

2. User Profile Retrieval and Caching

Before routing the message to Connect, the handler fetches the sender's Messenger profile using the Graph API. Unlike Instagram (which returns a single name field), Messenger provides first_name and last_name separately:

def get_user_profile(self, psid, fields=None):
    # Check in-memory cache first
    if psid in self.user_profiles:
        return self.user_profiles[psid]

    # Check DynamoDB users table
    if USERS_TABLE_NAME:
        users_table = TableService(table_name=USERS_TABLE_NAME)
        db_profile = users_table.get_item({"id": psid})
        if db_profile:
            return db_profile

    # Fetch from Graph API
    if fields is None:
        fields = ['first_name', 'last_name', 'profile_pic']

    params = {'fields': ','.join(fields), 'access_token': self.access_token}
    url = f"https://graph.facebook.com/v24.0/{psid}?{urlencode(params)}"
    # ... fetch and cache in DynamoDB with 7-day TTL

The display name is built by concatenating first_name and last_name, and this is what the agent sees in the Connect Chat widget.

3. Session Management

The handler checks DynamoDB for an existing chat session using the sender's PSID (Page-Scoped ID):

If a session exists, it sends the message using the stored connectionToken. If the token is expired (AccessDeniedException), it automatically creates a new session and cleans up the old record.
If no session exists, it calls StartChatContact to create a new Amazon Connect Chat, starts contact streaming to the SNS topic, creates a participant connection, and stores everything in DynamoDB.

The contact attributes include the channel name ("Messenger"), the customer ID (PSID), and the customer's display name — making it easy to identify the source channel in Contact Flows and agent routing.

attributes = {
    "Channel": "Messenger",
    "customerId": userId,
    "customerName": userName,
}

start_chat_response = self.connect.start_chat_contact(
    InstanceId=self.instance_id,
    ContactFlowId=self.contact_flow_id,
    Attributes=attributes,
    ParticipantDetails={"DisplayName": userName},
    InitialMessage={"ContentType": "text/plain", "Content": message},
    ChatDurationInMinutes=self.chat_duration_minutes,
)

4. Attachment Handling (Inbound)

When a customer sends an image, video, audio, or file on Messenger, the attachment data includes a type and a payload.url pointing to Meta's CDN. The handler downloads the file content and uploads it to the Connect Chat session:

def attachment_message_handler(message, connect_chat_service, table_service, user_name, sender_profile):
    # Ensure a chat session exists (create one if needed)
    # ...

    for attachment in message.attachments:
        att_url = attachment.get('payload', {}).get('url')

        # Download from Messenger CDN
        file_bytes, content_type = download_attachment(att_url)

        # Upload to Connect Chat via Participant API
        attachment_id, error = connect_chat_service.attach_file(
            fileContents=file_bytes,
            fileName=get_attachment_filename(attachment),
            fileType=content_type,
            ConnectionToken=connection_token
        )

The upload uses the same three-step Participant API flow: start_attachment_upload → PUT to pre-signed URL → complete_attachment_upload. If anything fails, the handler falls back to sending the CDN URL as a text message.

Outbound: Amazon Connect → Messenger

When an agent replies from the Amazon Connect workspace, the outbound path delivers the message back to Messenger.

1. Streaming Events via SNS

Amazon Connect publishes chat streaming events to an SNS topic. The Outbound Handler Lambda subscribes to this topic and processes three event types:

MESSAGE — text messages from the agent
ATTACHMENT — file attachments sent by the agent
EVENT — participant join/leave and chat ended events

Messages from the CUSTOMER role are skipped to avoid processing the customer's own messages again.

2. Sending Text Messages

For text messages with CUSTOMER or ALL visibility, the handler looks up the customer's PSID from DynamoDB and sends the reply via the Messenger Send API:

def send_messenger_text(access_token, text_message, recipient_id):
    url = f"https://graph.facebook.com/v24.0/me/messages"

    payload = {
        "recipient": {"id": recipient_id},
        "message": {"text": text_message},
    }

    url_with_token = f"{url}?access_token={quote(access_token)}"
    # POST to Messenger Send API

3. Sending Attachments

When an agent sends a file from the Connect Chat widget, the handler retrieves a signed URL for the attachment and forwards it to Messenger as a media message. The MIME type determines the Messenger attachment type:

MIME prefix	Messenger type
`image/*`	`image`
`video/*`	`video`
`audio/*`	`audio`
everything else	`file`

def send_messenger_attachment(access_token, attachment_url, mime_type, recipient_id):
    attachment_type = get_attachment_type(mime_type)  # image, video, audio, or file

    payload = {
        "recipient": {"id": recipient_id},
        "message": {
            "attachment": {
                "type": attachment_type,
                "payload": {"url": attachment_url, "is_reusable": True}
            }
        },
    }
    # POST to Messenger Send API

The is_reusable: True flag tells Meta to cache the attachment, which can speed up delivery if the same file is sent to multiple recipients.

4. Session Cleanup

When a participant leaves or the chat ends, the handler deletes the connection record from DynamoDB so the next inbound message starts a fresh session.

Message Types Supported

Direction	Text	Images	Videos	Audio	Files
Inbound (customer → agent)	✅	✅	—	—	✅
Outbound (agent → customer)	✅	✅	—	—	✅

What Gets Deployed

Resource	Service	Purpose
`/messages` endpoint (GET & POST)	API Gateway	Receives Meta webhook verification and inbound messages
Inbound Handler	Lambda	Processes Messenger messages and routes them to Amazon Connect Chat
Outbound Handler	Lambda	Sends agent replies back to Messenger via the Send API
Active Connections table	DynamoDB	Tracks open chat sessions (`contactId` PK, `userId` GSI)
Messenger Users table	DynamoDB	Caches Messenger user profiles (TTL-based expiry)
`messages_out` topic	SNS	Delivers Amazon Connect streaming events to the Outbound Handler
`messenger-page-token`	Secrets Manager	Stores the Facebook Page Access Token
`/meta/messenger/config`	SSM Parameter Store	Holds Connect instance ID, contact flow ID, verification token
`/meta/messenger/webhook/url`	SSM Parameter Store	Stores the deployed API Gateway callback URL

Cost Estimation

Example scenario: 1,000 conversations per month, averaging 10 messages each (5 inbound + 5 outbound), totaling 10,000 messages.

Component	Estimated Monthly Cost	Notes
Infrastructure (API GW, Lambda, DynamoDB, SNS, Secrets Manager)	~$0.71	Negligible at this scale
Amazon Connect Chat (Inbound)	$20.00	5,000 msgs × $0.004/msg
Amazon Connect Chat (Outbound)	$20.00	5,000 msgs × $0.004/msg
Total	~$40.71

The infrastructure cost is minimal — Amazon Connect Chat messaging is the primary cost driver at $0.004 per message in each direction. See Amazon Connect pricing for current rates.

To reduce Connect Chat costs on high-volume conversations, consider adding a message buffering layer to aggregate rapid consecutive messages.

Deployment Prerequisites

Before getting started you'll need:

Facebook Page and Meta App

You need a Facebook Page and a Meta App configured with the Messenger Platform. The main steps are:

Have or create a Meta Business Account
Create a Meta App and add the Messenger product
Connect your Facebook Page and generate a Page Access Token
Generate a non-expiring Page Access Token (short-lived tokens expire in ~1-2 hours)

See the Facebook Setup Guide for detailed step-by-step instructions, including the token exchange flow to get a non-expiring token.

⚠️ Important: In development mode, your app can only receive messages from Facebook accounts with a role on the Meta App (Admin, Developer, Tester). For production use, you need App Review with Advanced Access for pages_messaging.

An Amazon Connect Instance

You need an Amazon Connect instance. If you don't have one yet, you can follow this guide to create one.

You'll need the INSTANCE_ID of your instance. You can find it in the Amazon Connect console or in the instance ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

A Chat Flow to Handle Messages

Create or have ready the contact flow that defines the user experience. Follow this guide to create an Inbound Contact Flow. The simplest one will work.

Remember to publish the flow.

Take note of the INSTANCE_ID and CONTACT_FLOW_ID from the Details tab. The values are in the flow ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(see the Amazon Connect Prerequisites for more details)

Deploying with AWS CDK

⚠️ Deploy in the same region where your Amazon Connect instance is configured.

1. Clone the repository and navigate to the project

git clone https://github.com/aws-samples/sample-amazon-connect-social-integration.git
cd sample-amazon-connect-social-integration/facebook-messenger-connect-chat

2. Deploy with CDK

Follow the instructions in the CDK Deployment Guide for environment setup and deployment commands.

Post-deployment Configuration

Step 1: Update the Page Access Token in Secrets Manager

The stack creates a Secrets Manager secret named messenger-page-token with a placeholder value. Update it with your actual non-expiring Page Access Token.

See Facebook Setup Guide — Step 5 for how to generate a non-expiring token.

Step 2: Update the SSM Configuration Parameter

After deployment, go to AWS Systems Manager - Parameter Store and update the SSM parameter /meta/messenger/config with your Amazon Connect and Facebook details:

Parameter	Description
`instance_id`	Your Amazon Connect Instance ID
`contact_flow_id`	The ID of the Inbound Contact Flow for chat
`MESSENGER_VERIFICATION_TOKEN`	A secret string you choose — must match what you enter in the Meta webhook config

Step 3: Configure the Webhook in Meta App Dashboard

Go to your Meta App Dashboard → Messenger → Settings → Webhooks
Set the Callback URL to the API Gateway URL. You can find it in the SSM parameter /meta/messenger/webhook/url in AWS Systems Manager - Parameter Store
Set the Verify Token to the same value you used for MESSENGER_VERIFICATION_TOKEN above
Subscribe to the messages webhook field (at minimum)
Subscribe your Page to the app so it receives webhook events

For full details, see Facebook Setup Guide — Step 4.

Testing

Go to your Amazon Connect instance and open the Contact Control Panel (CCP).

Try these scenarios:

Send a message to your Facebook Page from another Facebook account — it should appear as a new chat contact in the CCP
Reply from the CCP — the response should arrive in the customer's Messenger chat
Send an image from Messenger — it should appear as an image attachment in the agent's chat
Send a file (PDF, document) from Messenger — it should appear as a file attachment
From the agent side, send an image or document — it should appear in the customer's Messenger chat

Important Considerations around Facebook Messenger

24-Hour Messaging Window

Facebook Messenger has a 24-hour standard messaging window:

After a user sends a message, your Page has 24 hours to respond
Outside this window, you can only send messages using Message Tags (limited use cases)
Each new user message reopens the 24-hour window

Rate Limits

Messenger Platform has rate limits based on your app's usage tier
Monitor API response headers for rate limit information
Implement exponential backoff for retries

App Review

In development mode, your app can only receive messages from accounts with a role on the app (Admin, Developer, Tester)
For production use with real customers, you need to submit for App Review and request Advanced Access for pages_messaging

Page Access Token Security

The Page Access Token grants full messaging access to your Page — treat it like a password
Store it in AWS Secrets Manager (as this solution does), never in code or environment variables
Use the non-expiring token flow described in the Facebook Setup Guide to avoid token rotation issues

Next Steps

This solution handles the core Messenger-to-Connect messaging flow. Some ideas to extend it:

Use Amazon Bedrock to analyze inbound images and provide agents with context
Use Amazon Connect AI Agents for agentic self-service, letting customers resolve common issues without waiting for a human agent
Combine with the Instagram DM integration to handle both Meta channels from a single Amazon Connect instance

Leverage Amazon Connect Customer Profiles

This solution already fetches Messenger profile data (first name, last name, profile picture) and passes it as contact attributes. You can take this further by integrating with Amazon Connect Customer Profiles to give agents a unified view of the customer across channels. Then in your Contact Flow, use the Customer Profiles block to retrieve the profile and display it in the agent workspace. The agent sees the customer's name, previous interaction history, and data from other channels — all before they even type a reply.

Resources

Expandiendo Amazon Connect a Facebook Messenger

ensamblador — Wed, 01 Apr 2026 18:00:00 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Aprende cómo conectar Facebook Messenger con Amazon Connect Chat para una atención al cliente fluida. Esta guía paso a paso cubre la arquitectura completa usando AWS CDK, AWS Lambda, Amazon API Gateway, Amazon DynamoDB y Amazon Connect. Desde recibir mensajes de clientes hasta enrutarlos a agentes, reenviar respuestas de agentes a Messenger y manejar archivos adjuntos en ambas direcciones — todo con gestión automática de sesiones, prevención de loops echo y caché de perfiles de usuario vía Graph API.

Facebook Messenger tiene más de mil millones de usuarios activos. Muchos de ellos ya están enviando mensajes a tu Página de Facebook con preguntas sobre productos, estado de pedidos o solicitudes de soporte. Si tus agentes tienen que alternar entre Meta Business Suite y su contact center, se pierde contexto y los tiempos de respuesta se resienten.

En este blog, aprenderás cómo conectar Facebook Messenger directamente a Amazon Connect Chat, para que tus agentes manejen conversaciones de Messenger desde el mismo workspace que usan para todos los demás canales. Los mensajes fluyen en ambas direcciones — incluyendo imágenes, documentos y archivos — con gestión automática de sesiones y enriquecimiento de perfiles de usuario.

Revisa el código en Github

Qué vas a construir

Un puente de mensajería bidireccional entre Facebook Messenger y Amazon Connect que:

Recibe mensajes entrantes de Messenger vía webhooks de Meta y los enruta a Amazon Connect Chat
Reenvía las respuestas de los agentes desde Amazon Connect de vuelta a Messenger a través del Send API
Gestiona sesiones de chat automáticamente — creando nuevas, reutilizando activas y limpiando las expiradas
Obtiene y cachea perfiles de usuario de Messenger (nombre, apellido, foto de perfil) vía Graph API
Maneja archivos adjuntos en ambas direcciones — imágenes y archivos de clientes, e imágenes y archivos de agentes
Previene loops echo filtrando mensajes enviados por tu propia Página

El resultado final: los agentes ven las conversaciones de Messenger como contactos de chat regulares en su workspace de Amazon Connect, con el nombre real del cliente.

Arquitectura

Así funciona el flujo:

Un cliente envía un mensaje en Facebook Messenger. Meta entrega el evento webhook a un endpoint de API Gateway
La Lambda del Inbound Handler valida el webhook, parsea el mensaje y busca o crea una sesión de Amazon Connect Chat
El perfil de Messenger del cliente se obtiene vía Graph API y se cachea en DynamoDB
Los mensajes de texto y archivos adjuntos se envían a la sesión de Connect Chat vía el Participant API
Cuando un agente responde, Amazon Connect publica el evento a un topic SNS vía contact streaming
La Lambda del Outbound Handler recibe el evento SNS, busca el Page-Scoped ID (PSID) del cliente y envía la respuesta a través del Messenger Send API

Entrante: Messenger → Amazon Connect

Cuando un cliente envía un mensaje a tu Página de Facebook, el flujo entrante maneja todo, desde la validación del webhook hasta la entrega del mensaje.

1. Validación del Webhook y Parseo de Mensajes

Meta envía eventos webhook a tu endpoint /messages de API Gateway. La Lambda maneja solicitudes GET para verificación del webhook — Meta envía los parámetros hub.mode, hub.verify_token y hub.challenge que deben ser validados y devueltos.

Para solicitudes POST, la clase MessengerService parsea el payload del webhook. Los webhooks de Messenger llegan con object: "page" y contienen entries con datos de mensajería:

class MessengerMessage:
    def __init__(self, messaging_data):
        self.sender_id = messaging_data.get('sender', {}).get('id')
        self.recipient_id = messaging_data.get('recipient', {}).get('id')
        self.timestamp = messaging_data.get('timestamp')

        message_data = messaging_data.get('message', {})
        self.message_id = message_data.get('mid')
        self.text = message_data.get('text')
        self.attachments = message_data.get('attachments', [])

        if self.text:
            self.message_type = 'text'
        elif len(self.attachments):
            self.message_type = 'attachment'
        else:
            self.message_type = 'unknown'

El servicio filtra mensajes enviados por tu propio Page ID para prevenir loops echo — cuando tu Página envía una respuesta, Meta también la entrega como evento webhook, y sin este filtro tendrías un ciclo infinito.

2. Obtención y Caché de Perfiles de Usuario

Antes de enrutar el mensaje a Connect, el handler obtiene el perfil de Messenger del remitente usando el Graph API. A diferencia de Instagram (que retorna un solo campo name), Messenger proporciona first_name y last_name por separado:

def get_user_profile(self, psid, fields=None):
    # Verificar caché en memoria primero
    if psid in self.user_profiles:
        return self.user_profiles[psid]

    # Verificar tabla de usuarios en DynamoDB
    if USERS_TABLE_NAME:
        users_table = TableService(table_name=USERS_TABLE_NAME)
        db_profile = users_table.get_item({"id": psid})
        if db_profile:
            return db_profile

    # Obtener del Graph API
    if fields is None:
        fields = ['first_name', 'last_name', 'profile_pic']

    params = {'fields': ','.join(fields), 'access_token': self.access_token}
    url = f"https://graph.facebook.com/v24.0/{psid}?{urlencode(params)}"
    # ... obtener y cachear en DynamoDB con TTL de 7 días

El nombre para mostrar se construye concatenando first_name y last_name, y esto es lo que el agente ve en el widget de Connect Chat.

3. Gestión de Sesiones

El handler verifica en DynamoDB si existe una sesión de chat activa usando el PSID (Page-Scoped ID) del remitente:

Si existe una sesión, envía el mensaje usando el connectionToken almacenado. Si el token expiró (AccessDeniedException), crea automáticamente una nueva sesión y limpia el registro anterior.
Si no existe sesión, llama a StartChatContact para crear un nuevo Amazon Connect Chat, inicia contact streaming al topic SNS, crea una conexión de participante y almacena todo en DynamoDB.

Los atributos de contacto incluyen el nombre del canal ("Messenger"), el ID del cliente (PSID) y el nombre para mostrar del cliente — facilitando identificar el canal de origen en Contact Flows y enrutamiento de agentes.

attributes = {
    "Channel": "Messenger",
    "customerId": userId,
    "customerName": userName,
}

start_chat_response = self.connect.start_chat_contact(
    InstanceId=self.instance_id,
    ContactFlowId=self.contact_flow_id,
    Attributes=attributes,
    ParticipantDetails={"DisplayName": userName},
    InitialMessage={"ContentType": "text/plain", "Content": message},
    ChatDurationInMinutes=self.chat_duration_minutes,
)

4. Manejo de Archivos Adjuntos (Entrante)

Cuando un cliente envía una imagen, video, audio o archivo en Messenger, los datos del adjunto incluyen un type y un payload.url apuntando al CDN de Meta. El handler descarga el contenido del archivo y lo sube a la sesión de Connect Chat:

def attachment_message_handler(message, connect_chat_service, table_service, user_name, sender_profile):
    # Asegurar que existe una sesión de chat (crear una si es necesario)
    # ...

    for attachment in message.attachments:
        att_url = attachment.get('payload', {}).get('url')

        # Descargar del CDN de Messenger
        file_bytes, content_type = download_attachment(att_url)

        # Subir a Connect Chat vía Participant API
        attachment_id, error = connect_chat_service.attach_file(
            fileContents=file_bytes,
            fileName=get_attachment_filename(attachment),
            fileType=content_type,
            ConnectionToken=connection_token
        )

La carga usa el mismo flujo de tres pasos del Participant API: start_attachment_upload → PUT a URL pre-firmada → complete_attachment_upload. Si algo falla, el handler envía la URL del CDN como mensaje de texto como fallback.

Saliente: Amazon Connect → Messenger

Cuando un agente responde desde el workspace de Amazon Connect, el flujo saliente entrega el mensaje de vuelta a Messenger.

1. Eventos de Streaming vía SNS

Amazon Connect publica eventos de streaming de chat a un topic SNS. La Lambda del Outbound Handler se suscribe a este topic y procesa tres tipos de eventos:

MESSAGE — mensajes de texto del agente
ATTACHMENT — archivos adjuntos enviados por el agente
EVENT — eventos de unión/salida de participantes y fin de chat

Los mensajes del rol CUSTOMER se omiten para evitar procesar los propios mensajes del cliente nuevamente.

2. Envío de Mensajes de Texto

Para mensajes de texto con visibilidad CUSTOMER o ALL, el handler busca el PSID del cliente en DynamoDB y envía la respuesta vía el Messenger Send API:

def send_messenger_text(access_token, text_message, recipient_id):
    url = f"https://graph.facebook.com/v24.0/me/messages"

    payload = {
        "recipient": {"id": recipient_id},
        "message": {"text": text_message},
    }

    url_with_token = f"{url}?access_token={quote(access_token)}"
    # POST al Messenger Send API

3. Envío de Archivos Adjuntos

Cuando un agente envía un archivo desde el widget de Connect Chat, el handler obtiene una URL firmada del adjunto y lo reenvía a Messenger como mensaje multimedia. El tipo MIME determina el tipo de adjunto de Messenger:

Prefijo MIME	Tipo Messenger
`image/*`	`image`
`video/*`	`video`
`audio/*`	`audio`
todo lo demás	`file`

def send_messenger_attachment(access_token, attachment_url, mime_type, recipient_id):
    attachment_type = get_attachment_type(mime_type)  # image, video, audio, o file

    payload = {
        "recipient": {"id": recipient_id},
        "message": {
            "attachment": {
                "type": attachment_type,
                "payload": {"url": attachment_url, "is_reusable": True}
            }
        },
    }
    # POST al Messenger Send API

El flag is_reusable: True le dice a Meta que cachee el adjunto, lo que puede acelerar la entrega si el mismo archivo se envía a múltiples destinatarios.

4. Limpieza de Sesiones

Cuando un participante sale o el chat termina, el handler elimina el registro de conexión de DynamoDB para que el próximo mensaje entrante inicie una sesión nueva.

Tipos de Mensajes Soportados

Dirección	Texto	Imágenes	Videos	Audio	Archivos
Entrante (cliente → agente)	✅	✅	—	—	✅
Saliente (agente → cliente)	✅	✅	—	—	✅

Qué se Despliega

Recurso	Servicio	Propósito
Endpoint `/messages` (GET & POST)	API Gateway	Recibe verificación de webhook de Meta y mensajes entrantes
Inbound Handler	Lambda	Procesa mensajes de Messenger y los enruta a Amazon Connect Chat
Outbound Handler	Lambda	Envía respuestas de agentes de vuelta a Messenger vía Send API
Tabla Active Connections	DynamoDB	Rastrea sesiones de chat abiertas (`contactId` PK, `userId` GSI)
Tabla Messenger Users	DynamoDB	Cachea perfiles de usuario de Messenger (expiración por TTL)
Topic `messages_out`	SNS	Entrega eventos de streaming de Amazon Connect al Outbound Handler
`messenger-page-token`	Secrets Manager	Almacena el Facebook Page Access Token
`/meta/messenger/config`	SSM Parameter Store	Contiene instance ID de Connect, contact flow ID, token de verificación
`/meta/messenger/webhook/url`	SSM Parameter Store	Almacena la URL del callback de API Gateway desplegado

Estimación de Costos

Escenario de ejemplo: 1,000 conversaciones por mes, promediando 10 mensajes cada una (5 entrantes + 5 salientes), totalizando 10,000 mensajes.

Componente	Costo Mensual Estimado	Notas
Infraestructura (API GW, Lambda, DynamoDB, SNS, Secrets Manager)	~$0.71	Despreciable a esta escala
Amazon Connect Chat (Entrante)	$20.00	5,000 msgs × $0.004/msg
Amazon Connect Chat (Saliente)	$20.00	5,000 msgs × $0.004/msg
Total	~$40.71

El costo de infraestructura es mínimo — la mensajería de Amazon Connect Chat es el principal generador de costos a $0.004 por mensaje en cada dirección. Consulta los precios de Amazon Connect para tarifas actuales.

Para reducir costos de Connect Chat en conversaciones de alto volumen, considera agregar una capa de buffering de mensajes para agregar mensajes consecutivos rápidos.

Prerrequisitos de Despliegue

Antes de comenzar necesitarás:

Página de Facebook y Meta App

Necesitas una Página de Facebook y una Meta App configurada con la Messenger Platform. Los pasos principales son:

Tener o crear una Meta Business Account
Crear una Meta App y agregar el producto Messenger
Conectar tu Página de Facebook y generar un Page Access Token
Generar un Page Access Token que no expire (los tokens de corta duración expiran en ~1-2 horas)

Consulta la Guía de Configuración de Facebook para instrucciones detalladas paso a paso, incluyendo el flujo de intercambio de tokens para obtener un token que no expire.

⚠️ Importante: En modo desarrollo, tu app solo puede recibir mensajes de cuentas de Facebook con un rol en la Meta App (Admin, Developer, Tester). Para uso en producción, necesitas App Review con Advanced Access para pages_messaging.

Una Instancia de Amazon Connect

Necesitas una instancia de Amazon Connect. Si aún no tienes una, puedes seguir esta guía para crear una.

Necesitarás el INSTANCE_ID de tu instancia. Lo puedes encontrar en la consola de Amazon Connect o en el ARN de la instancia:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

Un Flujo de Chat para Manejar Mensajes

Crea o ten listo el flujo de contacto que define la experiencia del usuario. Sigue esta guía para crear un Inbound Contact Flow. El más sencillo funcionará.

Recuerda publicar el flujo.

Toma nota del INSTANCE_ID y CONTACT_FLOW_ID en la pestaña de Detalles. Los valores están en el ARN del flujo:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(consulta los Prerrequisitos de Amazon Connect para más detalles)

Despliegue con AWS CDK

⚠️ Despliega en la misma región donde tu instancia de Amazon Connect está configurada.

1. Clona el repositorio y navega al proyecto

git clone https://github.com/aws-samples/sample-amazon-connect-social-integration.git
cd sample-amazon-connect-social-integration/facebook-messenger-connect-chat

2. Despliega con CDK

Sigue las instrucciones en la Guía de Despliegue CDK para configuración del entorno y comandos de despliegue.

Configuración Post-despliegue

Paso 1: Actualizar el Page Access Token en Secrets Manager

El stack crea un secreto en Secrets Manager llamado messenger-page-token con un valor placeholder. Actualízalo con tu Page Access Token real que no expire.

Consulta Guía de Configuración de Facebook — Paso 5 para saber cómo generar un token que no expire.

Paso 2: Actualizar el Parámetro de Configuración SSM

Después del despliegue, ve a AWS Systems Manager - Parameter Store y actualiza el parámetro SSM /meta/messenger/config con los detalles de Amazon Connect y Facebook:

Parámetro	Descripción
`instance_id`	Tu Amazon Connect Instance ID
`contact_flow_id`	El ID del Inbound Contact Flow para chat
`MESSENGER_VERIFICATION_TOKEN`	Un string secreto que tú eliges — debe coincidir con lo que ingreses en la configuración del webhook de Meta

Paso 3: Configurar el Webhook en el Meta App Dashboard

Ve a tu Meta App Dashboard → Messenger → Settings → Webhooks
Configura la Callback URL con la URL de API Gateway. La puedes encontrar en el parámetro SSM /meta/messenger/webhook/url en AWS Systems Manager - Parameter Store
Configura el Verify Token con el mismo valor que usaste para MESSENGER_VERIFICATION_TOKEN arriba
Suscríbete al campo de webhook messages (como mínimo)
Suscribe tu Página a la app para que reciba eventos webhook

Para más detalles, consulta Guía de Configuración de Facebook — Paso 4.

Pruebas

Ve a tu instancia de Amazon Connect y abre el Contact Control Panel (CCP).

Prueba estos escenarios:

Envía un mensaje a tu Página de Facebook desde otra cuenta de Facebook — debería aparecer como un nuevo contacto de chat en el CCP
Responde desde el CCP — la respuesta debería llegar al chat de Messenger del cliente
Envía una imagen desde Messenger — debería aparecer como un adjunto de imagen en el chat del agente
Envía un archivo (PDF, documento) desde Messenger — debería aparecer como un adjunto de archivo
Desde el lado del agente, envía una imagen o documento — debería aparecer en el chat de Messenger del cliente

Consideraciones Importantes sobre Facebook Messenger

Ventana de Mensajería de 24 Horas

Facebook Messenger tiene una ventana de mensajería estándar de 24 horas:

Después de que un usuario envía un mensaje, tu Página tiene 24 horas para responder
Fuera de esta ventana, solo puedes enviar mensajes usando Message Tags (casos de uso limitados)
Cada nuevo mensaje del usuario reabre la ventana de 24 horas

Límites de Tasa

Messenger Platform tiene límites de tasa basados en el nivel de uso de tu app
Monitorea los headers de respuesta del API para información de límites de tasa
Implementa backoff exponencial para reintentos

App Review

En modo desarrollo, tu app solo puede recibir mensajes de cuentas con un rol en la app (Admin, Developer, Tester)
Para uso en producción con clientes reales, necesitas enviar para App Review y solicitar Advanced Access para pages_messaging

Seguridad del Page Access Token

El Page Access Token otorga acceso completo de mensajería a tu Página — trátalo como una contraseña
Almacénalo en AWS Secrets Manager (como hace esta solución), nunca en código o variables de entorno
Usa el flujo de token que no expire descrito en la Guía de Configuración de Facebook para evitar problemas de rotación de tokens

Próximos Pasos

Esta solución maneja el flujo principal de mensajería Messenger-a-Connect. Algunas ideas para extenderla:

Usar Amazon Bedrock para analizar imágenes entrantes y dar contexto a los agentes
Usar Amazon Connect AI Agents para autoservicio agéntico, permitiendo a los clientes resolver problemas comunes sin esperar a un agente humano
Combinar con la integración de Instagram DM para manejar ambos canales de Meta desde una sola instancia de Amazon Connect

Aprovechar Amazon Connect Customer Profiles

Esta solución ya obtiene datos del perfil de Messenger (nombre, apellido, foto de perfil) y los pasa como atributos de contacto. Puedes ir más allá integrando con Amazon Connect Customer Profiles para dar a los agentes una vista unificada del cliente a través de canales. Luego en tu Contact Flow, usa el bloque Customer Profiles para recuperar el perfil y mostrarlo en el workspace del agente. El agente ve el nombre del cliente, historial de interacciones previas y datos de otros canales — todo antes de escribir una respuesta.

Recursos

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Respondiendo DMs de Instagram con Amazon Connect Chat

ensamblador — Wed, 01 Apr 2026 06:58:52 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Aprende cómo conectar los Mensajes Directos de Instagram con Amazon Connect Chat para una atención al cliente fluida. Esta guía paso a paso cubre la arquitectura completa usando AWS CDK, AWS Lambda, Amazon API Gateway, Amazon DynamoDB y Amazon Connect. Desde recibir DMs de clientes hasta enrutarlos a agentes, reenviar respuestas de agentes a Instagram y manejar archivos adjuntos en ambas direcciones — todo con gestión automática de sesiones y caché de perfiles de usuario.

Tus clientes ya están en Instagram. Navegan tus productos, revisan tus stories, y cuando tienen una pregunta — envían un DM. Si tu equipo de soporte tiene que alternar entre Instagram y su herramienta de contact center, estás perdiendo tiempo y contexto.

En este blog, aprenderás cómo responder los Mensajes Directos de Instagram directamente a Amazon Connect Chat, para que tus agentes manejen conversaciones de Instagram desde el mismo workspace que usan para todos los demás canales. Sin cambiar de app, sin copiar y pegar, sin mensajes perdidos.

Revisa el código en Github

Qué vas a construir

Un puente de mensajería bidireccional entre DMs de Instagram y Amazon Connect que:

Recibe DMs entrantes de Instagram vía webhooks de Meta y los enruta a Amazon Connect Chat
Reenvía las respuestas de los agentes desde Amazon Connect de vuelta a Instagram a través del Graph API
Gestiona sesiones de chat automáticamente — creando nuevas, reutilizando activas y limpiando las expiradas
Cachea perfiles de usuario de Instagram (nombre, username, foto de perfil, cantidad de seguidores) en DynamoDB para reducir llamadas al API
Maneja archivos adjuntos en ambas direcciones — imágenes de clientes, e imágenes y documentos de agentes

El resultado final: los agentes ven las conversaciones de Instagram como contactos de chat regulares en su workspace de Amazon Connect, con el nombre y la información de perfil del cliente.

Arquitectura

Así funciona el flujo:

Un cliente envía un DM en Instagram. Meta entrega el evento webhook a un endpoint de API Gateway
La Lambda del Inbound Handler valida el webhook, parsea el mensaje y busca o crea una sesión de Amazon Connect Chat
El perfil de Instagram del cliente se obtiene vía Graph API y se cachea en DynamoDB
Los mensajes de texto y archivos adjuntos se envían a la sesión de Connect Chat vía el Participant API
Cuando un agente responde, Amazon Connect publica el evento a un topic SNS vía contact streaming
La Lambda del Outbound Handler recibe el evento SNS, busca el ID de Instagram del cliente y envía la respuesta a través del Instagram Graph API

Entrante: Instagram → Amazon Connect

Cuando un cliente envía un DM a tu cuenta Business de Instagram, el flujo entrante maneja todo, desde la validación del webhook hasta la entrega del mensaje.

1. Validación del Webhook y Parseo de Mensajes

Meta envía eventos webhook a tu endpoint /messages de API Gateway. La Lambda primero maneja las solicitudes GET para verificación del webhook — Meta envía un token de desafío que debe ser devuelto con el token de verificación correcto.

Para solicitudes POST (mensajes reales), la clase InstagramService parsea el payload del webhook. Los webhooks de Instagram llegan con object: "instagram" y contienen entries con datos de mensajería:

class InstagramMessage:
    def __init__(self, messaging_data):
        self.sender_id = messaging_data.get('sender', {}).get('id')
        self.recipient_id = messaging_data.get('recipient', {}).get('id')
        self.timestamp = messaging_data.get('timestamp')

        message_data = messaging_data.get('message', {})
        self.message_id = message_data.get('mid')
        self.text = message_data.get('text')
        self.attachments = message_data.get('attachments', [])

        if self.text:
            self.message_type = 'text'
        elif len(self.attachments):
            self.message_type = 'attachment'
        else:
            self.message_type = 'unknown'

El servicio también filtra mensajes echo — mensajes enviados por tu propia cuenta de Instagram — para prevenir loops infinitos.

2. Obtención y Caché de Perfiles de Usuario

Antes de enrutar el mensaje a Connect, el handler obtiene el perfil de Instagram del remitente usando el Graph API. Esto le da al agente contexto sobre con quién está hablando:

def get_user_profile(self, instagram_scoped_id, fields=None):
    # Verificar caché en memoria primero
    if instagram_scoped_id in self.user_profiles:
        return self.user_profiles[instagram_scoped_id]

    # Verificar tabla de usuarios en DynamoDB
    if USERS_TABLE_NAME:
        users_table = TableService(table_name=USERS_TABLE_NAME)
        db_profile = users_table.get_item({"id": instagram_scoped_id})
        if db_profile:
            return db_profile

    # Obtener del Graph API como último recurso
    params = {'fields': ','.join(fields), 'access_token': self.access_token}
    url = f"https://graph.instagram.com/v24.0/{instagram_scoped_id}?{urlencode(params)}"
    # ... obtener y cachear

El perfil incluye campos como name, username, profile_pic, follower_count, is_user_follow_business e is_verified_user. Los perfiles se cachean en una tabla DynamoDB con un TTL de 7 días, así que las conversaciones repetidas se saltan la llamada al API.

3. Gestión de Sesiones

El handler verifica en DynamoDB si existe una sesión de chat activa usando el Instagram-scoped ID del remitente:

Si existe una sesión, envía el mensaje usando el connectionToken almacenado. Si el token expiró (AccessDeniedException), crea automáticamente una nueva sesión.
Si no existe sesión, llama a StartChatContact para crear un nuevo Amazon Connect Chat, inicia contact streaming al topic SNS, crea una conexión de participante y almacena todo en DynamoDB.

4. Manejo de Archivos Adjuntos (Entrante)

Cuando un cliente envía una imagen, el handler la descarga del CDN de Instagram y la sube a la sesión de Connect Chat usando el flujo de tres pasos del Participant API:

start_attachment_upload — crea un slot de carga con una URL pre-firmada
PUT a la URL pre-firmada — sube el contenido binario
complete_attachment_upload — finaliza la carga

Si la descarga o carga falla, el handler envía la URL del adjunto como mensaje de texto para que el agente aún tenga acceso al contenido.

Saliente: Amazon Connect → Instagram

Cuando un agente responde desde el workspace de Amazon Connect, el flujo saliente entrega el mensaje de vuelta a Instagram.

1. Eventos de Streaming vía SNS

Amazon Connect publica eventos de streaming de chat a un topic SNS. La Lambda del Outbound Handler se suscribe a este topic y procesa tres tipos de eventos:

MESSAGE — mensajes de texto del agente
ATTACHMENT — archivos adjuntos enviados por el agente
EVENT — eventos de unión/salida de participantes y fin de chat

Los mensajes del rol CUSTOMER se omiten para evitar loops echo.

2. Envío de Mensajes de Texto

Para mensajes de texto con visibilidad CUSTOMER o ALL, el handler busca el Instagram-scoped ID del cliente y el ID de la cuenta Business de Instagram en DynamoDB, luego envía la respuesta vía el Graph API:

def send_instagram_text(access_token, text_message, recipient_id, instagram_account_id):
    url = f"https://graph.instagram.com/v24.0/{instagram_account_id}/messages"

    payload = {
        "recipient": {"id": recipient_id},
        "message": {"text": text_message},
        "access_token": access_token,
    }
    # POST al Instagram Graph API

3. Envío de Archivos Adjuntos

Cuando un agente envía un archivo desde el widget de Connect Chat, el handler obtiene una URL firmada del adjunto y lo reenvía a Instagram como mensaje multimedia. El tipo MIME determina el tipo de mensaje de Instagram:

Prefijo MIME	Tipo Instagram
`image/*`	`image`
`video/*`	`video`
`audio/*`	`audio`
todo lo demás	`file`

4. Limpieza de Sesiones

Cuando un participante sale o el chat termina, el handler elimina el registro de conexión de DynamoDB para que el próximo mensaje entrante inicie una sesión nueva.

Tipos de Mensajes Soportados

Dirección	Texto	Imágenes	Documentos
Entrante (cliente → agente)	✅	✅	—
Saliente (agente → cliente)	✅	✅	✅

Enviar documentos desde la app de Instagram no es posible actualmente (limitaciones de la app de Instagram), pero los clientes pueden recibir documentos enviados por agentes desde Amazon Connect.

Qué se Despliega

Recurso	Servicio	Propósito
Endpoint `/messages` (GET & POST)	API Gateway	Recibe verificación de webhook de Meta y mensajes entrantes
Inbound Handler	Lambda	Procesa mensajes de Instagram y los enruta a Amazon Connect Chat
Outbound Handler	Lambda	Envía respuestas de agentes de vuelta a Instagram vía Graph API
Tabla Active Connections	DynamoDB	Rastrea sesiones de chat abiertas (`contactId` PK, `userId` GSI)
Tabla Instagram Users	DynamoDB	Cachea perfiles de usuario de Instagram (expiración por TTL)
Topic `messages_out`	SNS	Entrega eventos de streaming de Amazon Connect al Outbound Handler
`instagram-token`	Secrets Manager	Almacena el Instagram User Access Token
`/meta/instagram/config`	SSM Parameter Store	Contiene instance ID de Connect, contact flow ID, token de verificación e Instagram account ID
`/meta/instagram/webhook/url`	SSM Parameter Store	Almacena la URL del callback de API Gateway desplegado

Estimación de Costos

Escenario de ejemplo: 1,000 conversaciones por mes, promediando 10 mensajes cada una (5 entrantes + 5 salientes), totalizando 10,000 mensajes.

Componente	Costo Mensual Estimado	Notas
Infraestructura (API GW, Lambda, DynamoDB, SNS, Secrets Manager)	~$0.71	Despreciable a esta escala
Amazon Connect Chat (Entrante)	$20.00	5,000 msgs × $0.004/msg
Amazon Connect Chat (Saliente)	$20.00	5,000 msgs × $0.004/msg
Total	~$40.71

Para reducir costos de Connect Chat en conversaciones de alto volumen, considera agregar una capa de buffering de mensajes para agregar mensajes consecutivos rápidos.

Prerrequisitos de Despliegue

Antes de comenzar necesitarás:

Cuenta Business de Instagram y Meta App

Necesitas una cuenta de Instagram Business o Creator conectada a una Meta App con el API de Instagram configurado. Los pasos principales son:

Tener o crear una Meta Business Account
Crear una Meta App y agregar el producto de Instagram
Configurar Instagram Login y generar un Instagram User Access Token
Asegurarte de que tu cuenta de Instagram sea Business o Creator (las cuentas personales no soportan el Messaging API)

Consulta la Guía de Configuración de Instagram para instrucciones detalladas paso a paso.

⚠️ Importante: En modo desarrollo, tu app solo puede recibir mensajes de cuentas de Instagram con un rol en la Meta App.

Una Instancia de Amazon Connect

Necesitas una instancia de Amazon Connect. Si aún no tienes una, puedes seguir esta guía para crear una.

Necesitarás el INSTANCE_ID de tu instancia. Lo puedes encontrar en la consola de Amazon Connect o en el ARN de la instancia:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

Un Flujo de Chat para Manejar Mensajes

Crea o ten listo el flujo de contacto que define la experiencia del usuario. Sigue esta guía para crear un Inbound Contact Flow. El más sencillo funcionará.

Recuerda publicar el flujo.

Toma nota del INSTANCE_ID y CONTACT_FLOW_ID en la pestaña de Detalles. Los valores están en el ARN del flujo:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(consulta los Prerrequisitos de Amazon Connect para más detalles)

Despliegue con AWS CDK

⚠️ Despliega en la misma región donde tu instancia de Amazon Connect está configurada.

1. Clona el repositorio y navega al proyecto

git clone https://github.com/aws-samples/sample-amazon-connect-social-integration.git
cd sample-amazon-connect-social-integration/instagram-dm-connect-chat

2. Despliega con CDK

Sigue las instrucciones en la Guía de Despliegue CDK para configuración del entorno y comandos de despliegue.

Configuración Post-despliegue

Paso 1: Actualizar el Instagram Access Token en Secrets Manager

El stack crea un secreto en Secrets Manager llamado instagram-token con un valor placeholder. Actualízalo con tu Instagram User Access Token real.

Consulta la Guía de Configuración de Instagram para saber cómo generar este token.

Paso 2: Actualizar el Parámetro de Configuración SSM

Después del despliegue, ve a AWS Systems Manager - Parameter Store y actualiza el parámetro SSM /meta/instagram/config con los detalles de Amazon Connect e Instagram:

Parámetro	Descripción
`instance_id`	Tu Amazon Connect Instance ID
`contact_flow_id`	El ID del Inbound Contact Flow para chat
`INSTAGRAM_VERIFICATION_TOKEN`	Un string secreto que tú eliges — debe coincidir con lo que ingreses en la configuración del webhook de Meta
`instagram_account_id`	Tu Instagram Business Account ID (ver nota abajo)

Para encontrar tu instagram_account_id:

En tu Meta App Dashboard → Instagram → API Setup with Instagram Login → expande "1. Generate access tokens" → el ID está debajo de la cuenta de Instagram vinculada
O llama al Graph API:

curl -X GET "https://graph.instagram.com/me?fields=id,username,account_type,user_id&access_token=YOUR_IG_ACCESS_TOKEN"

El campo user_id en la respuesta es tu instagram_account_id.

Paso 3: Configurar el Webhook en el Meta App Dashboard

Ve a tu Meta App Dashboard → Instagram → API Setup with Instagram Login → Webhooks
Configura la Callback URL con la URL de API Gateway. La puedes encontrar en el parámetro SSM /meta/instagram/webhook/url
Configura el Verify Token con el mismo valor que usaste para INSTAGRAM_VERIFICATION_TOKEN arriba
Suscríbete al campo de webhook messages

Para más detalles, consulta la Guía de Configuración de Instagram.

Pruebas

Ve a tu instancia de Amazon Connect y abre el Contact Control Panel (CCP).

Prueba estos escenarios:

Envía un DM a tu cuenta Business de Instagram desde otra cuenta de Instagram — debería aparecer como un nuevo contacto de chat en el CCP
Responde desde el CCP — la respuesta debería llegar a los DMs de Instagram del cliente
Envía una imagen desde Instagram — debería aparecer como un adjunto de imagen en el chat del agente
Desde el lado del agente, envía una imagen o documento — debería aparecer en los DMs de Instagram del cliente

Consideraciones Importantes sobre Instagram

Ventana de Mensajería de 24 Horas

Instagram tiene una ventana de mensajería estándar de 24 horas:

Después de que un usuario envía un mensaje, tu cuenta tiene 24 horas para responder
Fuera de esta ventana, la mensajería está restringida
Cada nuevo mensaje del usuario reabre la ventana de 24 horas

Ventana de Agente Humano

Instagram proporciona una ventana de agente humano de 7 días para conversaciones que son escaladas a un agente humano. Esta ventana extendida permite a los agentes más tiempo para resolver problemas complejos.

App Review

En modo desarrollo, tu app solo puede recibir mensajes de cuentas de Instagram con un rol en la Meta App (Admin, Developer, Tester)
Para uso en producción con clientes reales, necesitas enviar para App Review y solicitar los permisos requeridos

Límites de Tasa

El Instagram Messaging API tiene límites de tasa basados en el nivel de uso de tu app
Monitorea los headers de respuesta del API para información de límites de tasa

Próximos Pasos

Esta solución maneja el flujo principal de mensajería Instagram-a-Connect. Algunas ideas para extenderla:

Agregar soporte para menciones y respuestas de Instagram Stories
Usar Amazon Bedrock para analizar imágenes entrantes y dar contexto a los agentes antes de que respondan
Usar Amazon Connect AI Agents para autoservicio agéntico, permitiendo a los clientes resolver problemas comunes sin esperar a un agente humano
Combinar con la integración de Facebook Messenger para manejar ambos canales de Meta desde una sola instancia de Amazon Connect

Aprovechar Amazon Connect Customer Profiles

Esta solución ya obtiene datos del perfil de Instagram (nombre, username, foto de perfil, cantidad de seguidores) y los pasa como atributos de contacto. Puedes ir más allá integrando con Amazon Connect Customer Profiles para dar a los agentes una vista unificada del cliente a través de canales. Luego en tu Contact Flow, usa el bloque Customer Profiles para recuperar el perfil y mostrarlo en el workspace del agente. El agente ve el nombre del cliente, su handle de Instagram, cantidad de seguidores y cualquier historial de interacciones previas — todo antes de escribir una respuesta.

Recursos

Instagram DMs to Amazon Connect Chat

ensamblador — Wed, 01 Apr 2026 06:33:57 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Learn how to bridge Instagram Direct Messages and Amazon Connect Chat for seamless customer service. This step-by-step guide covers the full architecture using AWS CDK, AWS Lambda, Amazon API Gateway, Amazon DynamoDB, and Amazon Connect. From receiving customer DMs to routing them to agents, forwarding agent replies back to Instagram, and handling attachments in both directions — all with automatic session management and user profile caching.

Your customers are already on Instagram. They browse your products, check your stories, and when they have a question — they send a DM. If your CX team has to switch between Instagram and their contact center, you're losing time and context.

In this blog, you'll learn how to connect Instagram Direct Messages directly to Amazon Connect Chat, so your agents can handle Instagram conversations from the same workspace they use for every other channel. No app switching, no copy-pasting, no lost messages.

Check out the code at Github

What you'll build

A bidirectional messaging bridge between Instagram DMs and Amazon Connect that:

Receives incoming Instagram DMs via Meta webhooks and routes them to Amazon Connect Chat
Forwards agent replies from Amazon Connect back to Instagram through the Graph API
Manages chat sessions automatically — creating new ones, reusing active ones, and cleaning up expired ones
Caches Instagram user profiles (name, username, profile picture, follower count) in DynamoDB to reduce API calls
Handles attachments in both directions — images from customers, and images and documents from agents

The end result: agents see Instagram conversations as regular chat contacts in their Amazon Connect workspace, complete with the customer's Instagram name and profile information.

Architecture

Here's how it flows:

A customer sends a DM on Instagram. Meta delivers the webhook event to an API Gateway endpoint
The Inbound Handler Lambda validates the webhook, parses the message, and looks up or creates an Amazon Connect Chat session
The customer's Instagram profile is fetched via the Graph API and cached in DynamoDB
Text messages and attachments are forwarded into the Connect Chat session via the Participant API
When an agent replies, Amazon Connect publishes the event to an SNS topic via contact streaming
The Outbound Handler Lambda picks up the SNS event, looks up the customer's Instagram ID, and sends the reply back through the Instagram Graph API

Inbound: Instagram → Amazon Connect

When a customer sends a DM to your Instagram Business account, the inbound path handles everything from webhook validation to message delivery.

1. Webhook Validation and Message Parsing

Meta sends webhook events to your API Gateway /messages endpoint. The Lambda first handles GET requests for webhook verification — Meta sends a challenge token that must be echoed back with the correct verification token.

For POST requests (actual messages), the InstagramService class parses the webhook payload. Instagram webhooks arrive with object: "instagram" and contain entries with messaging data:

class InstagramMessage:
    def __init__(self, messaging_data):
        self.sender_id = messaging_data.get('sender', {}).get('id')
        self.recipient_id = messaging_data.get('recipient', {}).get('id')
        self.timestamp = messaging_data.get('timestamp')

        message_data = messaging_data.get('message', {})
        self.message_id = message_data.get('mid')
        self.text = message_data.get('text')
        self.attachments = message_data.get('attachments', [])

        if self.text:
            self.message_type = 'text'
        elif len(self.attachments):
            self.message_type = 'attachment'
        else:
            self.message_type = 'unknown'

The service also filters out echo messages — messages sent by your own Instagram account — to prevent infinite loops.

2. User Profile Retrieval and Caching

Before routing the message to Connect, the handler fetches the sender's Instagram profile using the Graph API. This provides the agent with context about who they're talking to:

def get_user_profile(self, instagram_scoped_id, fields=None):
    # Check in-memory cache first
    if instagram_scoped_id in self.user_profiles:
        return self.user_profiles[instagram_scoped_id]

    # Check DynamoDB users table
    if USERS_TABLE_NAME:
        users_table = TableService(table_name=USERS_TABLE_NAME)
        db_profile = users_table.get_item({"id": instagram_scoped_id})
        if db_profile:
            return db_profile

    # Fetch from Graph API as last resort
    params = {'fields': ','.join(fields), 'access_token': self.access_token}
    url = f"https://graph.instagram.com/v24.0/{instagram_scoped_id}?{urlencode(params)}"
    # ... fetch and cache

The profile includes fields like name, username, profile_pic, follower_count, is_user_follow_business, and is_verified_user. Profiles are cached in a DynamoDB table with a 7-day TTL, so repeat conversations skip the API call entirely.

3. Session Management

The handler checks DynamoDB for an existing chat session using the sender's Instagram-scoped ID:

If a session exists, it sends the message using the stored connectionToken. If the token is expired (AccessDeniedException), it automatically creates a new session.
If no session exists, it calls StartChatContact to create a new Amazon Connect Chat, starts contact streaming to the SNS topic, creates a participant connection, and stores everything in DynamoDB.

4. Attachment Handling (Inbound)

When a customer sends an image, the handler downloads it from Instagram's CDN and uploads it to the Connect Chat session using the Participant API's three-step attachment flow:

start_attachment_upload — creates an upload slot with a pre-signed URL
PUT to the pre-signed URL — uploads the binary content
complete_attachment_upload — finalizes the upload

If the download or upload fails, the handler falls back to sending the attachment URL as a text message so the agent still has access to the content.

Outbound: Amazon Connect → Instagram

When an agent replies from the Amazon Connect workspace, the outbound path delivers the message back to Instagram.

1. Streaming Events via SNS

Amazon Connect publishes chat streaming events to an SNS topic. The Outbound Handler Lambda subscribes to this topic and processes three event types:

MESSAGE — text messages from the agent
ATTACHMENT — file attachments sent by the agent
EVENT — participant join/leave and chat ended events

Messages from the CUSTOMER role are skipped to avoid echo loops.

2. Sending Text Messages

For text messages with CUSTOMER or ALL visibility, the handler looks up the customer's Instagram-scoped ID and the Instagram Business Account ID from DynamoDB, then sends the reply via the Graph API:

def send_instagram_text(access_token, text_message, recipient_id, instagram_account_id):
    url = f"https://graph.instagram.com/v24.0/{instagram_account_id}/messages"

    payload = {
        "recipient": {"id": recipient_id},
        "message": {"text": text_message},
        "access_token": access_token,
    }
    # POST to Instagram Graph API

3. Sending Attachments

When an agent sends a file from the Connect Chat widget, the handler retrieves a signed URL for the attachment and forwards it to Instagram as a media message. The MIME type determines the Instagram message type:

MIME prefix	Instagram type
`image/*`	`image`
`video/*`	`video`
`audio/*`	`audio`
everything else	`file`

4. Session Cleanup

When a participant leaves or the chat ends, the handler deletes the connection record from DynamoDB so the next inbound message starts a fresh session.

Message Types Supported

Direction	Text	Images	Documents
Inbound (customer → agent)	✅	✅	—
Outbound (agent → customer)	✅	✅	✅

Sending documents from the Instagram user app is not currently possible (instagram app limitations), but customers can receive documents sent by agents from Amazon Connect.

What Gets Deployed

Resource	Service	Purpose
`/messages` endpoint (GET & POST)	API Gateway	Receives Meta webhook verification and inbound messages
Inbound Handler	Lambda	Processes Instagram messages and routes them to Amazon Connect Chat
Outbound Handler	Lambda	Sends agent replies back to Instagram via the Graph API
Active Connections table	DynamoDB	Tracks open chat sessions (`contactId` PK, `userId` GSI)
Instagram Users table	DynamoDB	Caches Instagram user profiles (TTL-based expiry)
`messages_out` topic	SNS	Delivers Amazon Connect streaming events to the Outbound Handler
`instagram-token`	Secrets Manager	Stores the Instagram User Access Token
`/meta/instagram/config`	SSM Parameter Store	Holds Connect instance ID, contact flow ID, verification token, and Instagram account ID
`/meta/instagram/webhook/url`	SSM Parameter Store	Stores the deployed API Gateway callback URL

Cost Estimation

Example scenario: 1,000 conversations per month, averaging 10 messages each (5 inbound + 5 outbound), totaling 10,000 messages.

Component	Estimated Monthly Cost	Notes
Infrastructure (API GW, Lambda, DynamoDB, SNS, Secrets Manager)	~$0.71	Negligible at this scale
Amazon Connect Chat (Inbound)	$20.00	5,000 msgs × $0.004/msg
Amazon Connect Chat (Outbound)	$20.00	5,000 msgs × $0.004/msg
Total	~$40.71

The infrastructure cost is minimal — Amazon Connect Chat messaging is the primary cost driver at $0.004 per message in each direction. See Amazon Connect pricing for current rates.

To reduce Connect Chat costs on high-volume conversations, consider adding a message buffering layer to aggregate rapid consecutive messages.

Deployment Prerequisites

Before getting started you'll need:

Instagram Business Account and Meta App

You need an Instagram Business or Creator account connected to a Meta App with the Instagram API configured. The main steps are:

Have or create a Meta Business Account
Create a Meta App and add the Instagram product
Configure Instagram Login and generate an Instagram User Access Token
Make sure your Instagram account is a Business or Creator account (personal accounts don't support the Messaging API)

See the Instagram Setup Guide for detailed step-by-step instructions.

⚠️ Important: In development mode, your app can only receive messages from Instagram accounts with a role on the Meta App.

An Amazon Connect Instance

You need an Amazon Connect instance. If you don't have one yet, you can follow this guide to create one.

You'll need the INSTANCE_ID of your instance. You can find it in the Amazon Connect console or in the instance ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

A Chat Flow to Handle Messages

Create or have ready the contact flow that defines the user experience. Follow this guide to create an Inbound Contact Flow. The simplest one will work.

Remember to publish the flow.

Take note of the INSTANCE_ID and CONTACT_FLOW_ID from the Details tab. The values are in the flow ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(see the Amazon Connect Prerequisites for more details)

Deploying with AWS CDK

⚠️ Deploy in the same region where your Amazon Connect instance is configured.

1. Clone the repository and navigate to the project

git clone https://github.com/aws-samples/sample-amazon-connect-social-integration.git
cd sample-amazon-connect-social-integration/instagram-dm-connect-chat

2. Deploy with CDK

Follow the instructions in the CDK Deployment Guide for environment setup and deployment commands.

Post-deployment Configuration

Step 1: Update the Instagram Access Token in Secrets Manager

The stack creates a Secrets Manager secret named instagram-token with a placeholder value. Update it with your actual Instagram User Access Token.

See the Instagram Setup Guide for how to generate this token.

Step 2: Update the SSM Configuration Parameter

After deployment, go to AWS Systems Manager - Parameter Store and update the SSM parameter /meta/instagram/config with your Amazon Connect and Instagram details:

Parameter	Description
`instance_id`	Your Amazon Connect Instance ID
`contact_flow_id`	The ID of the Inbound Contact Flow for chat
`INSTAGRAM_VERIFICATION_TOKEN`	A secret string you choose — must match what you enter in the Meta webhook config
`instagram_account_id`	Your Instagram Business Account ID (see note below)

To find your instagram_account_id:

In your Meta App Dashboard → Instagram → API Setup with Instagram Login → expand "1. Generate access tokens" → the ID is underneath the linked Instagram account
Or call the Graph API:

curl -X GET "https://graph.instagram.com/me?fields=id,username,account_type,user_id&access_token=YOUR_IG_ACCESS_TOKEN"

The user_id field in the response is your instagram_account_id.

Step 3: Configure the Webhook in Meta App Dashboard

Go to your Meta App Dashboard → Instagram → API Setup with Instagram Login → Webhooks
Set the Callback URL to the API Gateway URL. You can find it in the SSM parameter /meta/instagram/webhook/url
Set the Verify Token to the same value you used for INSTAGRAM_VERIFICATION_TOKEN above
Subscribe to the messages webhook field

For full details, see the Instagram Setup Guide.

Testing

Go to your Amazon Connect instance and open the Contact Control Panel (CCP).

Try these scenarios:

Send a DM to your Instagram Business account from another Instagram account — it should appear as a new chat contact in the CCP
Reply from the CCP — the response should arrive in the customer's Instagram DMs
Send an image from Instagram — it should appear as an image attachment in the agent's chat
From the agent side, send an image or document — it should appear in the customer's Instagram DMs

Important Considerations around Instagram

24-Hour Messaging Window

Instagram has a 24-hour standard messaging window:

After a user sends a message, your account has 24 hours to respond
Outside this window, messaging is restricted
Each new user message reopens the 24-hour window

Human Agent Messaging Window

Instagram provides a 7-day human agent messaging window for conversations that are escalated to a human agent. This extended window allows agents more time to resolve complex issues.

App Review

In development mode, your app can only receive messages from Instagram accounts with a role on the Meta App (Admin, Developer, Tester)
For production use with real customers, you need to submit for App Review and request the required permissions

Rate Limits

The Instagram Messaging API has rate limits based on your app's usage tier
Monitor API response headers for rate limit information

Next Steps

This solution handles the core Instagram-to-Connect messaging flow. Some ideas to extend it:

Add support for Instagram Stories mentions and replies
Use Amazon Bedrock to analyze inbound images and provide agents with context before they respond
Use Amazon Connect AI Agents for agentic self-service, letting customers resolve common issues without waiting for a human agent
Combine with the Facebook Messenger integration to handle both Meta channels from a single Amazon Connect instance

Leverage Amazon Connect Customer Profiles

This solution already fetches Instagram profile data (name, username, profile picture, follower count) and passes it as contact attributes. You can take this further by integrating with Amazon Connect Customer Profiles to give agents a unified view of the customer across channels. Then in your Contact Flow, use the Customer Profiles block to retrieve the profile and display it in the agent workspace. The agent sees the customer's name, Instagram handle, follower count, and any previous interaction history — all before they even type a reply.

Resources

[Boost]

ensamblador — Thu, 19 Mar 2026 05:54:18 +0000

Building Your Own AI-Powered StreamDeck with re:Button

Vinicius Senger ・ Feb 28

#diy #opensource #automation #ai

Manejo de Archivos Adjuntos (y notas de voz) entre WhatsApp y Amazon Connect

ensamblador — Mon, 02 Mar 2026 17:14:34 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Aprende a manejar archivos adjuntos en ambas direcciones entre WhatsApp y Amazon Connect — imágenes, documentos, audio y video. Esta guía paso a paso cubre la arquitectura completa usando AWS CDK, AWS Lambda, AWS End User Messaging Social, Amazon S3 y Amazon Connect. Desde descargar medios de WhatsApp hasta subirlos al Chat de Connect, reenviar archivos del agente de vuelta a WhatsApp, y procesar notas de voz con conversión de formato y transcripción en tiempo real usando Amazon Transcribe.

Los mensajes de texto son solo el comienzo. Los clientes envían fotos de productos dañados, PDFs de facturas, notas de voz explicando su problema, y a veces incluso videos. Si tu integración de WhatsApp con Amazon Connect solo maneja texto, te estás perdiendo una gran parte de la conversación.

En este blog, aprenderás a manejar archivos adjuntos en ambas direcciones — del cliente al agente y del agente al cliente — incluyendo un pipeline para convertir y transcribir notas de voz. Esto habilita casos de uso avanzados como reclamos de seguros con evidencia fotográfica, instrucciones de voz transcritas para el agente, e intercambio de documentos sin salir del chat.

Consulta el código en https://github.com/aws-samples

Lo que vas a construir

Una capa de manejo bidireccional de archivos adjuntos entre WhatsApp y Amazon Connect que:

Detecta y descarga medios de los mensajes entrantes de WhatsApp (imágenes, documentos, audio, video)
Convierte las notas de voz de WhatsApp (OGG/Opus) a WAV para compatibilidad con Connect
Transcribe las notas de voz en tiempo real usando Amazon Transcribe Streaming
Agrega esos archivos a la sesión de Chat de Amazon Connect para que los agentes puedan verlos
Reenvía los archivos enviados por los agentes desde el widget de Chat de Connect de vuelta a WhatsApp

El resultado final: agentes y clientes pueden intercambiar archivos de forma natural, y las notas de voz llegan tanto como audio reproducible como texto legible.

Arquitectura

Así funciona el flujo:

Un cliente envía un archivo o medio por WhatsApp. La Lambda del manejador de entrada lo descarga a S3 usando el AWS SDK
Si el archivo es una nota de voz (OGG), se convierte a WAV usando ffmpeg en una Lambda separada
El archivo se sube a la sesión de Chat de Amazon Connect a través de la API de Participante
Cuando un agente envía un archivo desde el widget de Chat de Connect, el manejador de salida detecta el evento ATTACHMENT
El manejador obtiene una URL firmada del archivo y lo envía a WhatsApp como mensaje de medios

Tipos de Mensajes de WhatsApp

Los mensajes de WhatsApp no son solo texto. El payload del webhook de Meta incluye un campo type que indica qué tipo de contenido envió el cliente. Cada tipo de medio lleva su contenido en un campo dedicado dentro del objeto del mensaje:

Tipo	Campo	Descripción
`text`	`text`	Mensaje de texto plano
`image`	`image`	Fotos, capturas de pantalla, memes
`document`	`document`	PDFs, hojas de cálculo, documentos de Word
`audio`	`audio`	Notas de voz (formato OGG/Opus)
`video`	`video`	Clips de video
`sticker`	`sticker`	Stickers de WhatsApp
`reaction`	`reaction`	Reacciones con emoji a mensajes

No todos son útiles en un contexto de atención al cliente. Los stickers y las reacciones típicamente agregan ruido en lugar de valor, por lo que la solución los hace configurables — puedes ignorarlos a través del parámetro SSM:

Tipos de Adjuntos Soportados en este proyecto

Dirección	Imágenes	Documentos	Audio	Video	Stickers	Reacciones
Entrada (WhatsApp → Connect)	✅	✅	✅ (convertido + transcrito)	N/I	Configurable	N/I
Salida (Connect → WhatsApp)	✅	✅	—	—	—	-

N/I: No implementado aquí, pero factible.

{
  "ignore_reactions": "yes",
  "ignore_stickers": "yes"
}

Para los tipos de medios (image, document, audio, video), el payload del mensaje incluye un media_id que usas para descargar el contenido real del archivo. El archivo en sí no está en el webhook — necesitas obtenerlo por separado.

Entrada: WhatsApp → Amazon Connect

Cuando un cliente envía un archivo por WhatsApp, la Lambda del manejador de entrada (whatsapp_event_handler) lo procesa en tres etapas: detección, descarga y subida.

1. Detección y Descarga

La clase WhatsappMessage inspecciona cada mensaje entrante en busca de campos de medios. Verifica audio, image, document, video y sticker en ese orden:

def get_attachment(self, download=True):
    attachment = None
    if self.message.get("audio"):
        attachment = self.message.get("audio")
    elif self.message.get("image"):
        attachment = self.message.get("image")
    elif self.message.get("document"):
        attachment = self.message.get("document")
    elif self.message.get("video"):
        attachment = self.message.get("video")
    elif self.message.get("sticker"):
        attachment = self.message.get("sticker")
    # reacciones no implementadas

    if not attachment:
        return {}

    # Descargar usando la API de Social Messaging
    media_content = self.download_media(
        media_id=attachment.get("id"),
        phone_id=self.phone_number_id,
        bucket_name=BUCKET_NAME,
        media_prefix=ATTACHMENT_PREFIX,
    )
    # Leer contenido binario desde S3
    binary = self.get_s3_file_content(media_content.get("location"))
    attachment.update({"content": binary})

El método download_media() llama a la API de End User Messaging Social (get_whatsapp_message_media), que descarga el archivo desde Meta a un bucket de S3. El archivo queda en s3://<bucket>/<prefix><media_id>.<extension> donde la extensión se deriva del tipo MIME.

2. Subida al Chat de Amazon Connect

Una vez que el archivo está en S3 y su contenido binario está cargado, la función process_attachment() lo sube a la sesión activa de Chat de Connect usando la API de Participante. Este es un proceso de tres pasos:

start_attachment_upload — crea un slot de subida, retorna una URL pre-firmada y un ID de adjunto
PUT a la URL pre-firmada — sube el contenido binario
complete_attachment_upload — finaliza la subida

def attach_file(self, fileContents, fileName, fileType, ConnectionToken):
    # Paso 1: Crear slot de subida
    attachResponse = participant_client.start_attachment_upload(
        ContentType=fileType,
        AttachmentSizeInBytes=fileSize,
        AttachmentName=fileName,
        ConnectionToken=ConnectionToken
    )

    # Paso 2: Subir a la URL pre-firmada
    upload_url = attachResponse['UploadMetadata']['Url']
    requests.put(
        upload_url,
        data=fileContents,
        headers=attachResponse['UploadMetadata']['HeadersToInclude'],
        timeout=30
    )

    # Paso 3: Finalizar
    participant_client.complete_attachment_upload(
        AttachmentIds=[attachResponse['AttachmentId']],
        ConnectionToken=ConnectionToken
    )

Salida: Amazon Connect → WhatsApp

Cuando un agente envía un archivo desde el widget de Chat de Connect, la Lambda del manejador de salida (connect_event_handler) lo captura y lo reenvía a WhatsApp.

1. Detección de Adjuntos

Amazon Connect publica eventos de streaming a un tema de SNS. El manejador verifica el campo Type en cada evento:

MESSAGE — mensaje de texto
ATTACHMENT — archivo adjunto
EVENT — eventos de entrada/salida de participantes

2. Obtención de URL Firmada

Para cada adjunto con Status: APPROVED, el manejador busca el número de teléfono del cliente y el número del sistema en DynamoDB usando el contactId, luego obtiene una URL de descarga temporal:

def get_signed_url(connectionToken, attachment):
    response = participant_client.get_attachment(
        AttachmentId=attachment,
        ConnectionToken=connectionToken
    )
    return response['Url']

3. Envío a WhatsApp

El manejador mapea el tipo MIME al tipo de mensaje de WhatsApp correspondiente y envía el archivo usando la URL firmada como enlace de medios — no es necesario volver a subir el archivo:

def send_whatsapp_attachment(attachment_url, mime_type, name, to, phone_number_id):
    message_type = get_file_category(mime_type)  # image, video, audio, o document
    message_object = {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": f"+{to}",
        "type": message_type,
    }
    message_object[message_type] = {"link": attachment_url}
    if message_type == "document":
        message_object[message_type]["filename"] = name

    socialessaging.send_whatsapp_message(
        originationPhoneNumberId=phone_number_id,
        metaApiVersion=meta_api_version,
        message=bytes(json.dumps(message_object), "utf-8"),
    )

Prefijo MIME	Tipo WhatsApp
`image/*`	`image`
`video/*`	`video`
`audio/*`	`audio`
todo lo demás	`document`

Para los tipos document, se preserva el nombre original del archivo para que el cliente vea un nombre significativo en su chat de WhatsApp.

Caso Especial. Procesamiento de Notas de Voz

Más allá del simple reenvío de archivos, los adjuntos pueden procesarse para habilitar casos de uso avanzados. El ejemplo más interesante en esta solución es el manejo de notas de voz — conversión de formatos de audio y transcripción de voz a texto.

El Problema con las Notas de Voz

Las notas de voz de WhatsApp llegan en formato OGG/Opus. El Chat de Amazon Connect no soporta archivos OGG como adjuntos. Si intentas subir un archivo OGG, será rechazado. Por eso necesitas un paso de conversión.

Conversión OGG → WAV

Una función Lambda dedicada (convert_to_wav) maneja la conversión de formato usando ffmpeg. Después de la conversión, el manejador de entrada lee el contenido WAV desde S3 y lo sube al Chat de Connect como voice.wav.

Transcripción en Tiempo Real con Amazon Transcribe Streaming

El archivo OGG original también se envía a una Lambda transcribe_audio para la conversión de voz a texto. Esta usa Amazon Transcribe Streaming — no la API por lotes — para obtener resultados en tiempo casi real.

Más Allá de las Notas de Voz: Ideas de Procesamiento Avanzado

El mismo patrón — interceptar, procesar, reenviar — puede extenderse a otros tipos de adjuntos para casos de uso avanzados:

Comprensión de imágenes: Usa Amazon Bedrock o Amazon Rekognition para analizar fotos. ¿Un cliente envía una foto de un producto dañado? Extrae una descripción y adjúntala al chat junto con la imagen. Útil para reclamos de seguros o solicitudes de garantía.
Análisis de video: Extrae fotogramas clave de los adjuntos de video y pásalos por modelos multimodales para su comprensión. ¿Un cliente envía un video de un dispositivo con fallas? Resume el problema para el agente.
Extracción de documentos: Usa Amazon Textract o Modelos de Base multimodales para extraer texto de documentos escaneados, facturas o formularios. Pre-llena los detalles del caso antes de que el agente abra el chat.
Detección de idioma y traducción: Detecta el idioma de las notas de voz o el texto en imágenes y tradúcelos antes de reenviarlos al agente.

El manejador de entrada está diseñado para ser extensible — puedes agregar pasos de procesamiento entre la descarga y la subida a Connect sin cambiar el flujo general.

Prerrequisitos de Despliegue

Antes de comenzar necesitarás:

Cuenta de WhatsApp Business

Para empezar, necesitas crear una nueva cuenta de WhatsApp Business (WABA) o migrar una existente a AWS. Los pasos principales se describen aquí. En resumen:

Tener o crear una cuenta de Meta Business
Acceder a la consola de AWS End User Messaging Social y vincular tu cuenta de negocio a través del portal integrado de Facebook
Asegurarte de tener un número de teléfono que pueda recibir verificación por SMS/voz y agregarlo a WhatsApp

⚠️ Importante: No uses tu número personal de WhatsApp para esto.

Una Instancia de Amazon Connect

Necesitas una instancia de Amazon Connect. Si aún no tienes una, puedes seguir esta guía para crear una.

Necesitarás el INSTANCE_ID de tu instancia. Puedes encontrarlo en la consola de Amazon Connect o en el ARN de la instancia:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

Un Flujo de Chat para Manejar Mensajes

Crea o ten listo el flujo de contacto que define la experiencia del usuario. Sigue esta guía para crear un flujo de contacto de entrada (Inbound Contact Flow). El más sencillo funcionará.

Recuerda publicar el flujo.

Toma nota del INSTANCE_ID y CONTACT_FLOW_ID desde la pestaña de Detalles. Los valores están en el ARN del flujo:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(consulta los Prerrequisitos de WhatsApp / Connect para más detalles)

Importante: Habilitar Adjuntos en la Instancia de Amazon Connect

Sigue estos pasos para habilitar el intercambio de adjuntos.

Despliegue con AWS CDK

⚠️ Despliega en la misma región donde están configurados tus números de WhatsApp en AWS End User Messaging.

1. Clona el repositorio y navega al proyecto

git clone https://github.com/aws-samples/sample-whatsapp-end-user-messaging-connect-chat.git
cd sample-whatsapp-end-user-messaging-connect-chat/whatsapp-eum-connect-chat

2. Despliega con CDK

Sigue las instrucciones en la Guía de Despliegue con CDK.

Configuración Post-despliegue

Paso 1: Actualizar el Parámetro SSM

Después del despliegue, actualiza el parámetro SSM /whatsapp_eum_connect_chat/config con los detalles de tu Amazon Connect:

{
  "instance_id": "<tu-connect-instance-id>",
  "contact_flow_id": "<tu-contact-flow-id>",
  "chat_duration_minutes": 60,
  "ignore_reactions": "yes",
  "ignore_stickers": "yes"
}

Parámetro	Descripción
`instance_id`	El ID de tu instancia de Amazon Connect
`contact_flow_id`	El ID del flujo de contacto de entrada para chat
`chat_duration_minutes`	Cuánto tiempo permanece activa la sesión de chat (por defecto: 60)
`ignore_reactions`	Si se ignoran las reacciones de WhatsApp (por defecto: yes)
`ignore_stickers`	Si se ignoran los stickers de WhatsApp (por defecto: yes)

Paso 2: Agregar el Destino de Eventos

Después de desplegar el stack, usa el tema SNS creado como destino de eventos en la consola de AWS End User Messaging Social.

Ve a AWS Systems Manager Parameter Store y copia el valor de /whatsapp_eum_connect_chat/topic/in (comienza con arn:aws:sns)

En la consola de AWS End User Messaging Social, selecciona el destino Amazon SNS y pega el Topic ARN del paso anterior

Paso 3: Configurar el Idioma de Transcripción (Opcional)

El idioma de transcripción está configurado en es-US (Español) por defecto. Para cambiarlo, edita el parámetro language_code en lambdas/code/transcribe_audio/transcribe.py:

stream = await self.transcribe_client.start_stream_transcription(
    language_code="en-US",  # Cambia al idioma deseado
    media_sample_rate_hz=48000,
    media_encoding="ogg-opus",
)

Pruebas

Ve a tu instancia de Amazon Connect y abre el Panel de Control de Contactos (CCP). Envía un mensaje de WhatsApp al número de End User Messaging Social.

Prueba estos escenarios:

Envía una foto — debería aparecer como un adjunto de imagen en el chat del agente
Envía un PDF — debería aparecer como un adjunto de documento
Envía una nota de voz — debería llegar como un archivo de audio WAV más una transcripción de texto
Desde el lado del agente, envía una imagen o documento — debería aparecer en el chat de WhatsApp del cliente

Próximos Pasos

Esta solución maneja el flujo principal de adjuntos. Algunas ideas para extenderla:

Modelo de Base multimodal para análisis de imágenes en fotos entrantes (por ejemplo, evaluación de daños para reclamos)
Implementar soporte para adjuntos de video entrantes
Soportar múltiples idiomas de transcripción con detección automática de idioma
Combinar con la solución de Buffering de Mensajes para agregar mensajes rápidos y la solución de WhatsApp Iniciado por el Agente para comunicación proactiva completa

Recursos

Handling Attachments (and voice notes) between Whatsapp and Amazon Connect.

ensamblador — Mon, 02 Mar 2026 16:41:39 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Learn how to handle file attachments in both directions between WhatsApp and Amazon Connect — images, documents, audio, and video. This step-by-step guide covers the full architecture using AWS CDK, AWS Lambda, AWS End User Messaging Social, Amazon S3, and Amazon Connect. From downloading WhatsApp media to uploading it into Connect Chat, forwarding agent files back to WhatsApp, and processing voice notes with format conversion and real-time transcription using Amazon Transcribe.

Text messages are just the beginning. Customers send photos of damaged products, PDFs of invoices, voice notes explaining their issue, and sometimes even videos. If your WhatsApp integration with Amazon Connect only handles text, you're missing a huge part of the conversation.

In this blog, you'll learn how to handle file attachments in both directions — customer to agent and agent to customer — including a pipeline for converting and transcribing voice notes using AWS Lambda. This enables advanced use cases like insurance claims with photo evidence, voice instructions transcribed for the agent, and document exchange without leaving the chat.

Check out the code at https://github.com/aws-samples

What you'll build

A bidirectional attachment handling layer between WhatsApp and Amazon Connect that:

Detects and downloads media from incoming WhatsApp messages (images, documents, audio, video)
Converts WhatsApp voice notes (OGG/Opus) to WAV for Connect compatibility
Transcribes voice notes in real time using Amazon Transcribe Streaming
Add those files into the Amazon Connect Chat session so agents can see them
Forwards files sent by agents from the Connect Chat widget back to WhatsApp

The end result: agents and customers can exchange files naturally, and voice notes arrive both as playable audio and as readable text.

Architecture

Here's how it flows:

A customer sends a file or media on WhatsApp. The inbound handler Lambda downloads it to S3 using AWS SDK.
If the file is a voice note (OGG), it's converted to WAV using ffmpeg in a separate Lambda
The file is uploaded to the Amazon Connect Chat session via the Participant API
When an agent sends a file from the Connect Chat widget, the outbound handler detects the ATTACHMENT event
The handler retrieves a signed URL for the file and sends it to WhatsApp as a media message

Understanding WhatsApp Message Types

WhatsApp messages aren't just text. The webhook payload from Meta includes a type field that tells you what kind of content the customer sent. Each media type carries its content in a dedicated field within the message object:

Type	Field	Description
`text`	`text`	Plain text message
`image`	`image`	Photos, screenshots, memes
`document`	`document`	PDFs, spreadsheets, Word docs
`audio`	`audio`	Voice notes (OGG/Opus format)
`video`	`video`	Video clips
`sticker`	`sticker`	WhatsApp stickers
`reaction`	`reaction`	Emoji reactions to messages

Not all of these are useful in a customer service context. Stickers and reactions typically add noise rather than value, so the solution makes them configurable — you can ignore them via the SSM parameter:

Supported Attachment Types in this project

Direction	Images	Documents	Audio	Video	Stickers	Reactions
Inbound (WhatsApp → Connect)	✅	✅	✅ (converted + transcribed)	N/I	Configurable	N/I
Outbound (Connect → WhatsApp)	✅	✅	—	—	—	-

N/I: Not implemented here, but feasible.

{
  "ignore_reactions": "yes",
  "ignore_stickers": "yes"
}

For media types (image, document, audio, video), the message payload includes a media_id that you use to download the actual file content. The file itself isn't in the webhook — you need to fetch it separately.

Inbound: WhatsApp → Amazon Connect

When a customer sends a file on WhatsApp, the inbound handler Lambda (whatsapp_event_handler) processes it through three stages: detection, download, and upload.

1. Detection and Download

The WhatsappMessage class inspects each incoming message for media fields. It checks for audio, image, document, video, and sticker in that order:

def get_attachment(self, download=True):
    attachment = None
    if self.message.get("audio"):
        attachment = self.message.get("audio")
    elif self.message.get("image"):
        attachment = self.message.get("image")
    elif self.message.get("document"):
        attachment = self.message.get("document")
    elif self.message.get("video"):
        attachment = self.message.get("video")
    elif self.message.get("sticker"):
        attachment = self.message.get("sticker")
    # reactions not implemented

    if not attachment:
        return {}

    # Download using the Social Messaging API
    media_content = self.download_media(
        media_id=attachment.get("id"),
        phone_id=self.phone_number_id,
        bucket_name=BUCKET_NAME,
        media_prefix=ATTACHMENT_PREFIX,
    )
    # Read binary content from S3
    binary = self.get_s3_file_content(media_content.get("location"))
    attachment.update({"content": binary})

The download_media() method calls the End User Messaging Social API (get_whatsapp_message_media), which downloads the file from Meta into an S3 bucket. The file lands at s3://<bucket>/<prefix><media_id>.<extension> where the extension is derived from the MIME type.

2. Upload to Amazon Connect Chat

Once the file is in S3 and its binary content is loaded, the process_attachment() function uploads it to the active Connect Chat session using the Participant API. This is a three-step process:

start_attachment_upload — creates an upload slot, returns a pre-signed URL and attachment ID
PUT to the pre-signed URL — uploads the binary content
complete_attachment_upload — finalizes the upload

def attach_file(self, fileContents, fileName, fileType, ConnectionToken):
    # Step 1: Create upload slot
    attachResponse = participant_client.start_attachment_upload(
        ContentType=fileType,
        AttachmentSizeInBytes=fileSize,
        AttachmentName=fileName,
        ConnectionToken=ConnectionToken
    )

    # Step 2: Upload to pre-signed URL
    upload_url = attachResponse['UploadMetadata']['Url']
    requests.put(
        upload_url,
        data=fileContents,
        headers=attachResponse['UploadMetadata']['HeadersToInclude'],
        timeout=30
    )

    # Step 3: Finalize
    participant_client.complete_attachment_upload(
        AttachmentIds=[attachResponse['AttachmentId']],
        ConnectionToken=ConnectionToken
    )

Outbound: Amazon Connect → WhatsApp

When an agent sends a file from the Connect Chat widget, the outbound handler Lambda (connect_event_handler) picks it up and forwards it to WhatsApp.

1. Attachment Detection

Amazon Connect publishes streaming events to an SNS topic. The handler checks the Type field in each event:

MESSAGE — text message
ATTACHMENT — file attachment
EVENT — participant join/leave events

2. Signed URL Retrieval

For each attachment with Status: APPROVED, the handler looks up the customer's phone number and the system phone number from DynamoDB using the contactId, then retrieves a temporary download URL:

def get_signed_url(connectionToken, attachment):
    response = participant_client.get_attachment(
        AttachmentId=attachment,
        ConnectionToken=connectionToken
    )
    return response['Url']

3. Send to WhatsApp

The handler maps the MIME type to the appropriate WhatsApp message type and sends the file using the signed URL as the media link — no need to re-upload the file:

def send_whatsapp_attachment(attachment_url, mime_type, name, to, phone_number_id):
    message_type = get_file_category(mime_type)  # image, video, audio, or document
    message_object = {
        "messaging_product": "whatsapp",
        "recipient_type": "individual",
        "to": f"+{to}",
        "type": message_type,
    }
    message_object[message_type] = {"link": attachment_url}
    if message_type == "document":
        message_object[message_type]["filename"] = name

    socialessaging.send_whatsapp_message(
        originationPhoneNumberId=phone_number_id,
        metaApiVersion=meta_api_version,
        message=bytes(json.dumps(message_object), "utf-8"),
    )

MIME prefix	WhatsApp type
`image/*`	`image`
`video/*`	`video`
`audio/*`	`audio`
everything else	`document`

For document types, the original filename is preserved so the customer sees a meaningful file name in their WhatsApp chat.

Special Case. Processing Voice Notes

Beyond simple file relay, attachments can be processed to enable advanced use cases. The most compelling example in this solution is voice note handling — converting audio formats and transcribing speech to text.

The Problem with Voice Notes

WhatsApp voice notes arrive in OGG/Opus format. Amazon Connect Chat does not support OGG files as attachments. If you try to upload an OGG file, it will be rejected. So you need a conversion step.

OGG → WAV Conversion

A dedicated Lambda function (convert_to_wav) handles the format conversion using ffmpeg. After conversion, the inbound handler reads the WAV content from S3 and uploads it to Connect Chat as voice.wav.

Real-Time Transcription with Amazon Transcribe Streaming

The original OGG file is also sent to a transcribe_audio Lambda for speech-to-text conversion. This uses Amazon Transcribe Streaming — not the batch API — for near real-time results.

Beyond Voice Notes: Advanced Processing Ideas

The same pattern — intercept, process, forward — can be extended to other attachment types for advanced use cases:

Image understanding: Use Amazon Bedrock or Amazon Rekognition to analyze photos. A customer sends a photo of a damaged product? Extract a description and attach it to the chat alongside the image. Useful for insurance claims or warranty requests.
Video analysis: Extract key frames from video attachments and run them through multimodal models for understanding. A customer sends a video of a malfunctioning device? Summarize the issue for the agent.
Document extraction: Use Amazon Textract or multimodal Foundation Models to extract text from scanned documents, invoices, or forms. Pre-fill case details before the agent even opens the chat.
Language detection and translation: Detect the language of voice notes or text in images and translate them before forwarding to the agent.

The inbound handler is designed to be extensible — you can add processing steps between the download and the upload to Connect without changing the overall flow.

Deployment Prerequisites

Before getting started you'll need:

WhatsApp Business Account

To get started, you need to create a new WhatsApp Business Account (WABA) or migrate an existing one to AWS. The main steps are described here. In summary:

Have or create a Meta Business Account
Access the AWS End User Messaging Social console and link your business account through the embedded Facebook portal
Make sure you have a phone number that can receive SMS/voice verification and add it to WhatsApp

⚠️ Important: Do not use your personal WhatsApp number for this.

An Amazon Connect Instance

You need an Amazon Connect instance. If you don't have one yet, you can follow this guide to create one.

You'll need the INSTANCE_ID of your instance. You can find it in the Amazon Connect console or in the instance ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

A Chat Flow to Handle Messages

Create or have ready the contact flow that defines the user experience. Follow this guide to create an Inbound Contact Flow. The simplest one will work.

Remember to publish the flow.

Take note of the INSTANCE_ID and CONTACT_FLOW_ID from the Details tab. The values are in the flow ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

(see the WhatsApp / Connect Prerequisites for more details)

Important: Enable Attachments in the Amazon Connect Instance

Follow this steps to enable attachment sharing.

Deploying with AWS CDK

⚠️ Deploy in the same region where your AWS End User Messaging WhatsApp numbers are configured.

1. Clone the repository and navigate to the project

git clone https://github.com/aws-samples/sample-whatsapp-end-user-messaging-connect-chat.git
cd sample-whatsapp-end-user-messaging-connect-chat/whatsapp-eum-connect-chat

2. Deploy with CDK

Follow the instructions in the CDK Deployment Guide.

Post-deployment Configuration

Step 1: Update the SSM Parameter

After deployment, update the SSM parameter /whatsapp_eum_connect_chat/config with your Amazon Connect details:

{
  "instance_id": "<your-connect-instance-id>",
  "contact_flow_id": "<your-contact-flow-id>",
  "chat_duration_minutes": 60,
  "ignore_reactions": "yes",
  "ignore_stickers": "yes"
}

Parameter	Description
`instance_id`	Your Amazon Connect Instance ID
`contact_flow_id`	The ID of the Inbound Contact Flow for chat
`chat_duration_minutes`	How long the chat session stays active (default: 60)
`ignore_reactions`	Whether to ignore WhatsApp reactions (default: yes)
`ignore_stickers`	Whether to ignore WhatsApp stickers (default: yes)

Step 2: Add the Event Destination

After deploying the stack, use the created SNS topic as your event destination in the AWS End User Messaging Social console.

Go to AWS Systems Manager Parameter Store and copy the value of /whatsapp_eum_connect_chat/topic/in (it starts with arn:aws:sns)

In the AWS End User Messaging Social console, select destination Amazon SNS and paste the Topic ARN from the previous step

Step 3: Configure Transcription Language (Optional)

The transcription language is set to es-US (Spanish) by default. To change it, edit the language_code parameter in lambdas/code/transcribe_audio/transcribe.py:

stream = await self.transcribe_client.start_stream_transcription(
    language_code="en-US",  # Change to your target language
    media_sample_rate_hz=48000,
    media_encoding="ogg-opus",
)

Testing

Go to your Amazon Connect instance and open the Contact Control Panel (CCP). Send a WhatsApp message to the End User Messaging Social number.

Try these scenarios:

Send a photo — it should appear as an image attachment in the agent's chat
Send a PDF — it should appear as a document attachment
Send a voice note — it should arrive as a WAV audio file plus a text transcription
From the agent side, send an image or document — it should appear in the customer's WhatsApp chat

Next Steps

This solution handles the core attachment flow. Some ideas to extend it:

Multimodal Foundation Model for image analysis on inbound photos (e.g., damage assessment for claims) or videos
Implement support for video inbound attachments
Support multiple transcription languages with automatic language detection
Combine with the Message Buffering solution to aggregate rapid messages and the Agent-Initiated WhatsApp solution for full proactive communication

Resources

El hábito más frecuente de los usuarios de WhatsApp (y como se puede manejar)

ensamblador — Fri, 27 Feb 2026 03:29:10 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Aprende a optimizar las integraciones de WhatsApp con Amazon Connect mediante el buffering de mensajes rápidos consecutivos en un solo mensaje coherente. Esta guía paso a paso cubre la arquitectura completa usando AWS CDK, DynamoDB Streams, AWS Lambda, AWS End User Messaging Social y Amazon Connect. Reduce costos y ofrece una experiencia de conversación natural para tus agentes.

Cuando los clientes se comunican por WhatsApp, rara vez envían un solo mensaje. Escriben rápido: "Hola", "Necesito ayuda", "con mi pedido", "P12345". Cada uno de esos mensajes genera un evento de webhook separado y, sin ninguna optimización, cada uno crea un mensaje de chat independiente en Amazon Connect. ¿El resultado? Una conversación fragmentada, un agente confundido y costos innecesarios.

En los chats con IA, normalmente evitamos que los usuarios envíen mensajes adicionales mientras el agente aún está procesando. Lamentablemente, con mensajes asincrónicos y programáticos, no podemos controlar eso. Pero sí podemos controlar cuánto tiempo esperamos antes de empezar a responder. Este blog no solo aplica para escenarios de WhatsApp a Connect, sino para cualquier canal de chat que enfrente el mismo desafío: SMS, mensajes directos en redes sociales y más.

En este blog, aprenderás a resolver esto con una capa de buffering de mensajes que agrega mensajes rápidos consecutivos de WhatsApp en un solo mensaje coherente antes de reenviarlos a Amazon Connect.

Consulta el código en https://github.com/aws-samples

Lo que vas a construir

Una capa de buffering entre AWS End User Messaging Social y Amazon Connect que:

Captura los mensajes entrantes de WhatsApp en una tabla de DynamoDB
Usa DynamoDB Streams con una ventana de agregación (tumbling window) para almacenar mensajes en buffer
Agrega mensajes de texto consecutivos del mismo remitente en uno solo
Reenvía el mensaje combinado a Amazon Connect como un único mensaje de chat

El resultado final: los agentes ven una conversación limpia y natural en lugar de una avalancha de mensajes fragmentados.

Arquitectura

Así funciona el flujo:

Un mensaje de WhatsApp llega a través de AWS End User Messaging Social y se publica en un tema de SNS
Una función Lambda (on_raw_messages) almacena cada mensaje en una tabla de DynamoDB (raw_messages)
DynamoDB Streams activa una función Lambda (message_aggregator) usando una ventana de agregación como buffer
El agregador agrupa, ordena y concatena los mensajes de texto del mismo remitente
El mensaje agregado se reenvía al manejador de eventos de WhatsApp, que crea o actualiza la sesión de chat en Amazon Connect

El Problema

Cuando los usuarios envían múltiples mensajes en rápida sucesión:

Mensaje 1: Hola
Mensaje 2: Necesito ayuda
Mensaje 3: con mi pedido
Mensaje 4: P12345

Sin buffering, cada mensaje crea un mensaje de chat separado en Amazon Connect. Esto genera:

Una conversación fragmentada difícil de seguir para los agentes
Costos más altos (cada mensaje se factura individualmente)
Múltiples invocaciones de Lambda aguas abajo

La Solución: Cómo Funciona el Buffering

1. Almacenamiento de Mensajes raw

Los mensajes entrantes de WhatsApp se almacenan en una tabla de DynamoDB (raw_messages) con:

Clave de partición: from (número de teléfono del remitente)
Clave de ordenamiento: id (ID del mensaje)
TTL habilitado para limpieza automática
DynamoDB Streams habilitado con ventana de agregación

Usar from como clave de partición e id como clave de ordenamiento garantiza que los mensajes del mismo usuario se almacenen juntos y caigan en el mismo shard, por lo que se procesan secuencialmente por el stream.

La Lambda function que maneja esto es sencilla:

def lambda_handler(event, context):
    records = event.get("Records", [])

    for record in records:
        sns = record.get("Sns", {})
        sns_message = json.loads(sns.get("Message", "{}"), parse_float=decimal.Decimal)
        webhook_entry = json.loads(sns_message.get("whatsAppWebhookEntry", {}))

        for change in webhook_entry.get("changes", []):
            value = change.get("value", {})
            metadata = value.get("metadata", {})
            contacts = value.get("contacts", [])

            for message in value.get("messages", []):
                item = message.copy()
                item["metadata"] = metadata
                item["messaging_product"] = value.get("messaging_product")

                # Almacenar en DynamoDB
                table.put_item(Item=item)

    return {'statusCode': 200}

2. Procesamiento del Stream con Ventana de Agregación

La ventana de agregación (tumbling window) es la clave de la estrategia de buffering. DynamoDB Streams activa la Lambda message_aggregator, pero en lugar de invocarla por cada registro individual, la ventana de agregación espera un número configurable de segundos (por defecto: 20) antes de invocar la función con todos los registros acumulados en esa ventana.

Cada shard invoca una sola Lambda, por lo que los mensajes del mismo usuario dentro de esa ventana se procesan todos juntos.

3. Lógica de Agregación

El agregador agrupa los mensajes por remitente, los ordena por marca de tiempo y concatena los mensajes de texto consecutivos con saltos de línea. Los mensajes que no son de texto (imágenes, audio, documentos, etc.) se preservan como elementos separados.

Entrada:
  Mensaje 1: Hola
  Mensaje 2: Necesito ayuda
  Mensaje 3: con mi pedido
  Mensaje 4: P12345

Salida (mensaje agregado único):
  Hola
  Necesito ayuda
  con mi pedido
  P12345

La lógica principal de agregación:

def lambda_handler(event, context):
    raw_records = event.get("Records", [])

    records = []
    for record in raw_records:
        if record.get("eventName") == "INSERT":
            new_image = record.get("dynamodb", {}).get("NewImage", {})
            deserialized = deserialize_dynamodb(new_image)
            records.append(deserialized)

    if len(records) == 0:
        return {"state": event.get('state', {})}

    aggregated = aggregate_all_messages(records)

    # Reenviar cada mensaje agregado al manejador de eventos de WhatsApp
    for agg in aggregated:
        lambda_client.invoke(
            FunctionName=os.environ['WHATSAPP_EVENT_HANDLER'],
            InvocationType='Event',
            Payload=json.dumps(agg)
        )

    return {"state": event.get('state', {})}

4. Reenvío a Amazon Connect

Una vez agregados, la Lambda invoca asincrónicamente la función Lambda WhatsApp Inbound, que crea o actualiza la sesión de chat en Amazon Connect con el mensaje combinado. El agente ve un mensaje limpio en lugar de cuatro mensajes separados.

Beneficios

Flujo de conversación natural: Múltiples mensajes rápidos aparecen como un solo mensaje coherente
Optimización de costos: Menos mensajes aguas abajo significa menores costos de chat en Amazon Connect
Limpieza automática: El TTL elimina los mensajes en crudo automáticamente
Escalable: DynamoDB Streams maneja alto rendimiento (hasta 10,000 registros por stream)
Confiable: El procesamiento del stream asegura que no se pierdan mensajes (entrega al menos una vez)

Estimación de Costos

Escenario de ejemplo: 1,000 mensajes raw agregados en 250 mensajes (suponiendo una proporción de 4:1). Los mensajes son respondidos por un agente humano.

Componente	Sin Buffering	Con Buffering	Ahorro
DynamoDB + Streams	—	~$0.0013	—
Lambda (todas las funciones)	—	~$0.00078	—
Infraestructura de Buffering	$0.00	~$0.002	—
Llamadas API entrantes	1,000 llamadas	250 llamadas	75% menos llamadas
Costo Chat Connect (entrada)	$4.00	$1.00	$3.00
Total	$4.00	~$1.00	~$3.00 (75%)

Ten en cuenta que el costo total de la comunicación considera Connect entrada y salida, así como EUM entrada y salida. Aquí solo estamos reduciendo los mensajes de entrada de Amazon Connect Chat.

Costo de Connect Chat: $0.004 × msg (entrada) + $0.004 × msg (salida). Ver precios
Costo de EUM: $0.005 × msg (entrada) + $0.005 × msg (salida). Ver precios

Prerrequisitos

Antes de comenzar necesitarás:

Cuenta de WhatsApp Business

Para empezar, necesitas crear una nueva cuenta de WhatsApp Business (WABA) o migrar una existente a AWS. Los pasos principales se describen aquí. En resumen:

Tener o crear una cuenta de Meta Business
Acceder a la consola de AWS End User Messaging Social y vincular tu cuenta de negocio a través del portal integrado de Facebook
Asegurarte de tener un número de teléfono que pueda recibir verificación por SMS/voz y agregarlo a WhatsApp

⚠️ Importante: No uses tu número personal de WhatsApp para esto.

Una Instancia de Amazon Connect

Necesitas una instancia de Amazon Connect. Si aún no tienes una, puedes seguir esta guía para crear una.

Necesitarás el INSTANCE_ID de tu instancia. Puedes encontrarlo en la consola de Amazon Connect o en el ARN de la instancia:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

Un Flujo de Chat para Manejar Mensajes

Crea o ten listo el flujo de contacto que define la experiencia del usuario. Sigue esta guía para crear un flujo de contacto de entrada (Inbound Contact Flow). El más sencillo funcionará.

Recuerda publicar el flujo.

Toma nota del INSTANCE_ID y CONTACT_FLOW_ID desde la pestaña de Detalles. Los valores están en el ARN del flujo:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

Despliegue con AWS CDK

⚠️ Despliega en la misma región donde están configurados tus números de WhatsApp en AWS End User Messaging.

1. Clona el repositorio y navega al proyecto

git clone https://github.com/aws-samples/sample-whatsapp-end-user-messaging-connect-chat.git
cd sample-whatsapp-end-user-messaging-connect-chat/whatsapp-eum-connect-chat

2. Despliega con CDK

Sigue las instrucciones en la Guía de Despliegue con CDK.

Configuración Post-despliegue

Paso 1: Actualizar el Parámetro SSM

Después del despliegue, actualiza el parámetro SSM /whatsapp_eum_connect_chat/config con los detalles de tu Amazon Connect:

{
  "instance_id": "<tu-connect-instance-id>",
  "contact_flow_id": "<tu-contact-flow-id>",
  "chat_duration_minutes": 60,
  "ignore_reactions": "yes",
  "ignore_stickers": "yes"
}

Parámetro	Descripción
`instance_id`	El ID de tu instancia de Amazon Connect
`contact_flow_id`	El ID del flujo de contacto de entrada para chat
`chat_duration_minutes`	Cuánto tiempo permanece activa la sesión de chat (por defecto: 60)
`ignore_reactions`	Si se ignoran las reacciones de WhatsApp (por defecto: yes)
`ignore_stickers`	Si se ignoran los stickers de WhatsApp (por defecto: yes)

Paso 2: Agregar el Destino de Eventos

Después de desplegar el stack, usa el tema SNS creado como destino de eventos en la consola de AWS End User Messaging Social.

Ve a AWS Systems Manager Parameter Store y copia el valor de /whatsapp_eum_connect_chat/topic/in (comienza con arn:aws:sns)

En la consola de AWS End User Messaging Social, selecciona el destino Amazon SNS y pega el Topic ARN del paso anterior

Paso 3: Ajustar el Tiempo de Buffer (Opcional)

La ventana de buffer por defecto es de 20 segundos. Si deseas cambiarla, edita BUFFER_IN_SECONDS en config.py y vuelve a desplegar:

BUFFER_IN_SECONDS = 20  # Cambia este valor (en segundos)

Pruebas

Ve a tu instancia de Amazon Connect y abre el Panel de Control de Contactos (CCP). Envía un mensaje de WhatsApp al número de End User Messaging Social.

Intenta enviar una secuencia rápida de mensajes y observa cómo llegan como un solo mensaje agregado en Amazon Connect.

Próximos Pasos

Aunque este blog se enfoca en WhatsApp y Amazon Connect, el patrón de buffering aplica de forma amplia. Cualquier canal de chat donde los usuarios envíen mensajes rápidos y asincrónicos — SMS, mensajes directos en redes sociales o integraciones personalizadas — puede beneficiarse del mismo enfoque. Si no puedes evitar que los usuarios envíen múltiples mensajes mientras se procesa una respuesta, al menos puedes controlar cuánto tiempo esperas antes de actuar.

Algunas ideas para extender esta solución:

Ajustar la ventana de buffer según tu caso de uso (más corta para tiempo real, más larga para ahorro de costos)
Agregar una Cola de Mensajes Fallidos (Dead Letter Queue) para el procesamiento fallido del stream
Implementar lógica de agregación personalizada para tipos de mensajes específicos (por ejemplo, agrupar imágenes)
Combinar con la solución de WhatsApp Iniciado por el Agente para comunicación bidireccional completa

Recursos

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

The Most Frequent Habit of WhatsApp Users (And How to Handle It)

ensamblador — Fri, 27 Feb 2026 03:28:52 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Learn how to optimize WhatsApp-to-Amazon Connect integrations by buffering rapid consecutive messages into a single coherent message. This step-by-step guide covers the full architecture using AWS CDK, DynamoDB Streams, AWS Lambda, AWS End User Messaging Social, and Amazon Connect.

When customers reach out via WhatsApp, they rarely send a single message. They type fast: "Hello", "I need help", "with my order", "P12345". Each of those messages triggers a separate webhook event, and without any optimization, each one creates a separate chat message in Amazon Connect. The result? A fragmented conversation, a confused agent, and unnecessary costs.

In AI-powered chats, we usually prevent users from sending additional messages while the agent is still processing. Unfortunately, with asynchronous and programmatic messages, we can't control that. But we can control how long we wait before starting to answer. This blog not only helps with WhatsApp-to-Connect scenarios but applies to every chat channel that faces the same challenge — SMS, social media DMs, and more.

In this blog, you'll learn how to solve that with a message buffering layer that aggregates rapid consecutive WhatsApp messages into a single, coherent message before forwarding them to Amazon Connect.

Check out the code at https://github.com/aws-samples

What you'll build

A buffering layer between AWS End User Messaging Social and Amazon Connect that:

Captures incoming WhatsApp messages in a DynamoDB table
Uses DynamoDB Streams with a tumbling window to buffer messages
Aggregates consecutive text messages from the same sender into one
Forwards the combined message to Amazon Connect as a single chat message

The end result: agents see a clean, natural conversation instead of a flood of fragmented messages.

Architecture

Here's how it flows:

A WhatsApp message arrives via AWS End User Messaging Social and is published to an SNS topic
A Lambda function (on_raw_messages) stores each message in a DynamoDB table (raw_messages)
DynamoDB Streams triggers a Lambda function (message_aggregator) using a tumbling window as a buffer
The aggregator groups, sorts, and concatenates text messages from the same sender
The aggregated message is forwarded to the WhatsApp event handler, which creates or updates the Amazon Connect chat session

The Problem

When users send multiple messages in quick succession:

Message 1: Hello
Message 2: I need help
Message 3: with my order
Message 4: P12345

Without buffering, each message creates a separate Amazon Connect chat message. This leads to:

A fragmented conversation that's hard for agents to follow
Higher costs (each message is billed individually)
Multiple Lambda invocations downstream

How Buffering Works

1. Raw Message Storage

Incoming WhatsApp messages are stored in a DynamoDB table (raw_messages) with:

Partition key: from (sender phone number)
Sort key: id (message ID)
TTL enabled for automatic cleanup
DynamoDB Streams enabled with a tumbling window

Using from as the partition key and id as the sort key guarantees that messages from the same user are stored together and fall into the same shard, so they are processed sequentially by the stream.

The Lambda that handles this is straightforward:

def lambda_handler(event, context):
    records = event.get("Records", [])

    for record in records:
        sns = record.get("Sns", {})
        sns_message = json.loads(sns.get("Message", "{}"), parse_float=decimal.Decimal)
        webhook_entry = json.loads(sns_message.get("whatsAppWebhookEntry", {}))

        for change in webhook_entry.get("changes", []):
            value = change.get("value", {})
            metadata = value.get("metadata", {})
            contacts = value.get("contacts", [])

            for message in value.get("messages", []):
                item = message.copy()
                item["metadata"] = metadata
                item["messaging_product"] = value.get("messaging_product")

                # Store in DynamoDB
                table.put_item(Item=item)

    return {'statusCode': 200}

2. Stream Processing with Tumbling Window

The tumbling window is the key to the buffering strategy. DynamoDB Streams triggers the message_aggregator Lambda, but instead of invoking it for every single record, the tumbling window waits a configurable number of seconds (default: 20) before invoking the function with all accumulated records in that window.

Each shard invokes one Lambda, so messages from the same user within that window are processed altogether.

Look here if you want to dive deep.

3. Aggregation Logic

The aggregator groups messages by sender, sorts them by timestamp, and concatenates consecutive text messages with newlines. Non-text messages (images, audio, documents, etc.) are preserved as separate items.

Input:
  Message 1: Hello
  Message 2: I need help
  Message 3: with my order
  Message 4: P12345

Output (single aggregated message):
  Hello
  I need help
  with my order
  P12345

The core aggregation logic:

def lambda_handler(event, context):
    raw_records = event.get("Records", [])

    records = []
    for record in raw_records:
        if record.get("eventName") == "INSERT":
            new_image = record.get("dynamodb", {}).get("NewImage", {})
            deserialized = deserialize_dynamodb(new_image)
            records.append(deserialized)

    if len(records) == 0:
        return {"state": event.get('state', {})}

    aggregated = aggregate_all_messages(records)

    # Forward each aggregated message to the WhatsApp event handler
    for agg in aggregated:
        lambda_client.invoke(
            FunctionName=os.environ['WHATSAPP_EVENT_HANDLER'],
            InvocationType='Event',
            Payload=json.dumps(agg)
        )

    return {"state": event.get('state', {})}

4. Forwarding to Amazon Connect

Once aggregated, the Lambda asynchronously invokes the WhatsApp event handler, which creates or updates the Amazon Connect chat session with the combined message. The agent sees one clean message instead of four separate ones.

Benefits

Natural conversation flow: Multiple rapid messages appear as one coherent message
Cost optimization: Fewer messages downstream means lower Amazon Connect chat costs
Automatic cleanup: TTL removes old raw messages automatically
Scalable: DynamoDB Streams handles high throughput (up to 10,000 records per stream)
Reliable: Stream processing ensures no messages are lost (at-least-once delivery)

Cost Estimation

Example scenario: 1,000 raw messages aggregated into 250 messages (4:1 ratio assumption). Messages are answered by a human agent.

Component	Without Buffering	With Buffering	Savings
DynamoDB + Streams	—	~$0.0013	—
Lambda (all functions)	—	~$0.00078	—
Buffering Infrastructure	$0.00	~$0.002	—
Inbound API Calls	1,000 calls	250 calls	75% fewer calls
Connect Chat (In) Cost	$4.00	$1.00	$3.00
Total	$4.00	~$1.00	~$3.00 (75%)

Note the whole cost considers connect in and out as well EUM in and out. Here we are only reducing Amazon Connect Chat in messages.

Connect Chat cost: $0.004 × msg (in) + $0.004 × msg (out). See pricing
EUM cost: $0.005 × msg (in) + $0.005 × msg (out). See pricing

Prerequisites

Before getting started you'll need:

WhatsApp Business Account

To get started, you need to create a new WhatsApp Business Account (WABA) or migrate an existing one to AWS. The main steps are described here. In summary:

Have or create a Meta Business Account
Access the AWS End User Messaging Social console and link your business account through the embedded Facebook portal
Make sure you have a phone number that can receive SMS/voice verification and add it to WhatsApp

⚠️ Important: Do not use your personal WhatsApp number for this.

An Amazon Connect Instance

You need an Amazon Connect instance. If you don't have one yet, you can follow this guide to create one.

You'll need the INSTANCE_ID of your instance. You can find it in the Amazon Connect console or in the instance ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

A Chat Flow to Handle Messages

Create or have ready the contact flow that defines the user experience. Follow this guide to create an Inbound Contact Flow. The simplest one will work.

Remember to publish the flow.

Take note of the INSTANCE_ID and CONTACT_FLOW_ID from the Details tab. The values are in the flow ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID/contact-flow/CONTACT_FLOW_ID

Deploying with AWS CDK

⚠️ Deploy in the same region where your AWS End User Messaging WhatsApp numbers are configured.

1. Clone the repository and navigate to the project

git clone https://github.com/aws-samples/sample-whatsapp-end-user-messaging-connect-chat.git
cd sample-whatsapp-end-user-messaging-connect-chat/whatsapp-eum-connect-chat

2. Deploy with CDK

Follow the instructions in the CDK Deployment Guide.

Post-deployment Configuration

Step 1: Update the SSM Parameter

After deployment, update the SSM parameter /whatsapp_eum_connect_chat/config with your Amazon Connect details:

{
  "instance_id": "<your-connect-instance-id>",
  "contact_flow_id": "<your-contact-flow-id>",
  "chat_duration_minutes": 60,
  "ignore_reactions": "yes",
  "ignore_stickers": "yes"
}

Parameter	Description
`instance_id`	Your Amazon Connect Instance ID
`contact_flow_id`	The ID of the Inbound Contact Flow for chat
`chat_duration_minutes`	How long the chat session stays active (default: 60)
`ignore_reactions`	Whether to ignore WhatsApp reactions (default: yes)
`ignore_stickers`	Whether to ignore WhatsApp stickers (default: yes)

Step 2: Add the Event Destination

After deploying the stack, use the created SNS topic as your event destination in the AWS End User Messaging Social console.

Go to AWS Systems Manager Parameter Store and copy the value of /whatsapp_eum_connect_chat/topic/in (it starts with arn:aws:sns)

In the AWS End User Messaging Social console, select destination Amazon SNS and paste the Topic ARN from the previous step

Step 3: Adjust the Buffer Time (Optional)

The default buffer window is 20 seconds. If you want to change it, edit BUFFER_IN_SECONDS in config.py and redeploy:

BUFFER_IN_SECONDS = 20  # Change this value (in seconds)

Testing

Go to your Amazon Connect instance and open the Contact Control Panel (CCP). Send a WhatsApp message to the End User Messaging Social number.

Try sending a rapid sequence of messages and see how they arrive as a single aggregated message in Amazon Connect.

Next Steps

This solution is a starting point. Some ideas to extend it:

Adjust the buffer window based on your use case (shorter for real-time, longer for cost savings)
Add a Dead Letter Queue for failed stream processing
Implement custom aggregation logic for specific message types (e.g., group images together)
Combine with the Agent-Initiated WhatsApp solution for full bidirectional communication
Project Repository
Amazon Connect Administrator Guide
Amazon Connect API Reference
AWS End User Messaging Social User Guide
DynamoDB Streams Developer Guide
Build scalable, event-driven architectures with Amazon DynamoDB and AWS Lambda

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Agent-Initiated WhatsApp Messages from Amazon Connect

ensamblador — Thu, 26 Feb 2026 02:46:05 +0000

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.

Learn how to build a proactive WhatsApp messaging experience from Amazon Connect, enabling customer service agents to send WhatsApp template messages with a single click from the Agent Workspace. This step-by-step guide covers the full architecture using AWS CDK, AWS Lambda, AWS End User Messaging Social, and Amazon Connect, including the configuration of Contact Flows, custom forms (Views), and Lambda functions to retrieve customer data and send messages. Ideal for teams looking to automate and simplify outbound WhatsApp communication without leaving the Amazon Connect console.

Does your customer service team need to send proactive WhatsApp messages? Imagine an agent being able to send a WhatsApp template message to a customer with a single click, right from their Amazon Connect desktop. No switching apps, no copy-pasting phone numbers, no mistakes.

In this blog I'll show you how to build that experience using AWS CDK, AWS Lambda, AWS End User Messaging Social, and Amazon Connect.

Check out the code at https://github.com/aws-samples

What are we building?

A guided experience inside the Amazon Connect Agent Workspace that allows agents to:

See customer data pre-loaded in a form
Review and edit WhatsApp template parameters
Send the message with a single click

All orchestrated by a Contact Flow, Lambda functions, and a custom form (Connect view).

Architecture

Here's how it flows:

A Contact Flow invokes a Lambda function (get_customer_data) to retrieve customer information (name, phone number, etc.). You can also use the Customer Profile block to look up customer information in Connect Customer Profiles.
The flow presents a form (View) in the Agent Workspace with pre-filled data
The agent reviews, edits if needed, and submits
A second Lambda function (send_whatsapp_message) sends the WhatsApp template message via the AWS End User Messaging Social API

Prerequisites

Before getting started you'll need:

WhatsApp Business Account

To get started, you need to create a new WhatsApp Business Account (WABA) or migrate an existing one to AWS. The main steps are described here. In summary:

Have or create a Meta Business account
Access the AWS End User Messaging Social console and link your business account through the embedded Facebook portal
Make sure you have a phone number that can receive SMS/voice verification and add it to WhatsApp

⚠️ Important: Do not use your personal WhatsApp number for this.

An Amazon Connect Instance

You need an Amazon Connect instance. If you don't have one yet, you can follow this guide to create one.

You'll need the INSTANCE_ID of your instance. You can find it in the Amazon Connect console or in the instance ARN:

arn:aws:connect:<region>:<account_id>:instance/INSTANCE_ID

(see the WhatsApp / Connect Prerequisites for more details)

WhatsApp Message Template Creation

A WhatsApp message template created in End User Messaging (see the Template Creation Guide)

Deploying with AWS CDK

⚠️ Deploy in the same region where your AWS End User Messaging WhatsApp numbers are configured.

1. Clone the repository and navigate to the project

git clone https://github.com/aws-samples/sample-whatsapp-end-user-messaging-connect-chat.git
cd sample-whatsapp-end-user-messaging-connect-chat/agent-initiated-whatsapp

2. Set the Instance ID

Edit config.py and set your Amazon Connect Instance ID:

INSTANCE_ID = "<your-connect-instance-id>"

3. Deploy with CDK

Follow the instructions in the CDK Deployment Guide.

Post-deployment configuration

Once deployed, there are a few manual steps to wire everything together.

Step 1: Update the SSM Parameter

Go to AWS Systems Manager Parameter Store and update /whatsapp_template/config with your template configuration:

{
  "message": {
    "messaging_product": "whatsapp",
    "to": "PHONE_NUMBER",
    "recipient_type": "individual",
    "type": "template",
    "template": {
      "name": "your_template_name",
      "language": { "code": "en_US" },
      "components": [
        {
          "type": "body",
          "parameters": []
        }
      ]
    }
  },
  "META_API_VERSION": "v23.0",
  "ORIGINATION_PHONE_NUMBER_ID": "<your-origination-phone-number-id>"
}

Parameter	Description
`template.name`	Name of your WhatsApp template created in End User Messaging
`template.language.code`	Template language code (e.g.: `en_US`)
`ORIGINATION_PHONE_NUMBER_ID`	The phone number ID in AWS End User Messaging Social
`META_API_VERSION`	Meta API version (default: `v23.0`)

Step 2: Explore the deployed form

Navigate to the views in your Amazon Connect instance:

https://<your-instance>.my.connect.aws/views

Look for the view named enviarWhatsAppForm007. This is the form that agents will use to review customer data and send the message.

Note: the WhatsApp field is of type password to hide the number. It could even be removed from the form entirely and accessed using Contact Attributes.

Step 3: Configure the deployed Contact Flow

Navigate to the contact flow SendWhatsAppGuideFlow007 in your Amazon Connect console.

3.1 Configure the first Lambda (Get customer data)

Edit the first Invoke AWS Lambda function block and select the pre-deployed Lambda function. Look for the one containing GetCustomerData in the name.

This is a mock function that returns sample data:

def lambda_handler(event, context):
    return {
        "fullName": "John Doe",
        "phoneNumber": "+XXXXXXXX",
        "input4": "Delivered",
        "input3": "Puzzle 1000 pieces",
        "input2": "P12345",
        "input1": "John",
    }

Replace this with your own data source. For example, you could do a data dip to Amazon Connect Customer Profiles using a profileId, query a DynamoDB table, or call an external API.

Click Confirm to save.

3.2 Configure the Show View block

Edit the Show view block and select enviarWhatsAppForm007 as the view resource.

The form default values are mapped from the values returned by the Lambda:

fullName → $.External.fullName
whatsappNumber → $.External.phoneNumber
input1 to input4 → $.External.input1 to $.External.input4

These values pre-fill the form so the agent can review them before sending. Click Confirm to save.

3.3 Configure the second Lambda (Send WhatsApp message)

Edit the second Invoke AWS Lambda function block and select the Lambda containing SendWhatsappMessage in the ARN.

This Lambda reads the template configuration from SSM, extracts the form values from the contact attributes, and sends the message:

def lambda_handler(event, context):
    # Load the template configuration from SSM Parameter Store
    config = get_ssm_parameter(CONFIG_PARAM_NAME)
    message_payload = config["message"]

    # Extract form values from contact attributes
    attributes = event["Details"]["ContactData"]["Attributes"]
    phone_number = attributes.get("phoneNumber")

    # Build template parameters from input1..input4
    template_params = build_template_parameters(
        attributes, ["input1", "input2", "input3", "input4"]
    )

    # Send using AWS End User Messaging Social
    response = social_client.send_whatsapp_message(
        originationPhoneNumberId=origination_phone_number_id,
        message=bytes(json.dumps(message_payload), "utf-8"),
        metaApiVersion=meta_api_version,
    )
    return {"result": "OK", "messageId": response.get("messageId", "")}

Click Confirm to save. Then Save and Publish the contact flow.

Step 4: Create a new View (Guide)

Navigate to the Amazon Connect views:

https://<your-instance>.my.connect.aws/views

Create a new view of type Guide.

4.1 Add a Connect Application component

Drag a Connect Application component onto the canvas.

4.2 Configure the component

Set the contactFlowId to the deployed contact flow SendWhatsAppGuideFlow007.

4.3 Name and publish

Give the view a name and click Publish.

Step 5: Create a custom Workspace

5.1 Create the workspace

Navigate to the Amazon Connect workspaces:

https://<your-instance>.my.connect.aws/workspaces

Click Add new workspace and fill in the name, description, and title.

Assign this workspace to the users or routing profiles you need.

5.2 Add a page with the guide

Add a new page using Set page with custom page slug and select the view you created in the previous step (the one with the Connect Application component).

Use a custom slug like:

/page/send_whatsapp

Save the page.

5.3 Navigate to the custom workspace

Select your custom workspace from the top navigation bar in the Agent Workspace.

The agent can now navigate to the custom page and use the guide to send WhatsApp template messages to customers.

Demo

When the agent navigates to the custom page, they are presented with a Connect Application that runs the contact flow. The flow displays the form with pre-loaded values from the customer data Lambda, giving the agent the opportunity to review, modify, and submit. Once the agent submits, the WhatsApp sending Lambda is invoked with all the form parameters to deliver the final message.

Next steps

This solution is a starting point. Some ideas to extend it:

Connect the customer data Lambda to Amazon Connect Customer Profiles or DynamoDB
Add additional validations to the form
Support multiple WhatsApp templates selectable by the agent
Dynamically incorporate the number of inputs, depending on the number of variables in the template

Resources

Let's Build!

Autor:

ensambladorFollow

AWS Specialist Solutions Architect Applied AI @ AWS Opinions expressed are solely my own and do not express the views or opinions of my employer.