Notificaciones de Flows

Last update: 4 days ago by Irais Aguirre

Resumen para integración
Entrega: WhatsApp → Concepto Móvil → POST al webhook de plataforma configurado para la cuenta (no al webhook por número), con un JSON en el cuerpo. Solo se entregan cuando la cuenta tiene una plataforma configurada.
Encabezados: Content-Type: application/json; charset=UTF-8 y Authorization: Basic … opcional. No se envía Cache-Control.
Reintentos: no se reintenta ante códigos HTTP de error; solo se reintenta ante errores de I/O.
Formato: el objeto completo del webhook de Meta (object, entry, changes), con field igual a "flows" (ver Webhook).
Tipos en esta página: FLOW_STATUS_CHANGE, CLIENT_ERROR_RATE, ENDPOINT_ERROR_RATE, ENDPOINT_LATENCY, ENDPOINT_AVAILABILITY, FLOW_VERSION_EXPIRY_WARNING (valores de event)

Para la respuesta que envía el usuario al completar un Flow, consulta WhatsApp Flows en Respuestas de mensajes interactivos.

Estructura general

Las notificaciones de Flows (cambios de estatus y alertas de un Flow) se reciben por webhook. Son una combinación de objetos anidados de matrices JSON y objetos que contienen información sobre un cambio.

Estructura

Campos de Estructura general:

Nombre	Descripción	Tipo
object	El webhook al que se ha suscrito una empresa.	String
entry	Una serie de objetos de entrada. Los objetos de entrada tienen las siguientes propiedades: `id` (String). El ID de la cuenta empresarial de WhatsApp de la empresa que está suscrita al webhook. `changes` (Object). Matriz de objetos. Una serie de objetos de cambio. Los objetos de cambio tienen las siguientes propiedades: `value` (Object). `field` (String). flows	Lista objetos

Objeto value

Contiene detalles del cambio que es disparado por el webhook. Este objeto está anidado dentro de la matriz changes del array entry.

Nombre	Descripción	Tipo
flow_id	Identificador del Flow.	String
threshold	El umbral de alerta que se alcanzó.	Number
event	Tipo de notificación. Posibles valores: FLOW_STATUS_CHANGE CLIENT_ERROR_RATE ENDPOINT_ERROR_RATE ENDPOINT_LATENCY ENDPOINT_AVAILABILITY FLOW_VERSION_EXPIRY_WARNING	String
message	Descripción detallada del mensaje.	String
old_status	Estatus previo del Flow: DRAFT PUBLISHED DEPRECATED BLOCKED THROTTLED	String
new_status	Estatus actual del Flow: DRAFT PUBLISHED DEPRECATED BLOCKED THROTTLED	String
alert_state	Estatus de la alerta: ACTIVATED DEACTIVATED	String
requests_count	Número de solicitudes utilizadas para calcular la métrica.	Integer
errors	Una matriz de objetos de error que describen cada error incluido en la alerta. Los objetos de error tienen las siguientes propiedades: `error_count` (Integer). Número de ocurrencias del error. `error_rate` (Number, decimal). Tasa de error específica del error. `error_type` (String). Nombre del error.	Lista objetos
p50_latency	P50 Latencia de las solicitudes del endpoint.	Integer
p90_latency	P90 Latencia de las solicitudes del endpoint.	Integer
error_rate	Tasa de error general de la alerta.	Number (decimal)
availability	Disponibilidad del endpoint del Flow (porcentaje).	Number
warning	Advertencia de congelación o expiración de la versión del Flow. Presente en los eventos `FLOW_VERSION_EXPIRY_WARNING` y, al crear un Flow, también puede aparecer en un evento `FLOW_STATUS_CHANGE`.	String

Cambio de estatus del Flow

El campo event es "FLOW_STATUS_CHANGE".

Ejemplo

Ejemplo completo de Cambio de estatus del Flow:

Creación del Flow

{
    "entry": [
        {
            "id": "173276950931742",
            "time": 1718654293,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow Flow for Customer Support New has been created with DRAFT status",
                        "flow_id": "474277461763971",
                        "new_status": "DRAFT"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

De DRAFT a PUBLISHED

{
    "entry": [
        {
            "id": "173276950931742",
            "time": 1718663619,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow Mi flow para encuestar changed status from DRAFT to PUBLISHED",
                        "flow_id": "1191878175570507",
                        "old_status": "DRAFT",
                        "new_status": "PUBLISHED"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

De PUBLISHED a DEPRECATED

{
    "entry": [
        {
            "id": "173276950931742",
            "time": 1718728797,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow dev_prueba_2 changed status from PUBLISHED to DEPRECATED",
                        "flow_id": "1504323267150344",
                        "old_status": "PUBLISHED",
                        "new_status": "DEPRECATED"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

CLIENT_ERROR_RATE

El campo event es "CLIENT_ERROR_RATE".

Ejemplo

Ejemplo completo de CLIENT_ERROR_RATE:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "CLIENT_ERROR_RATE",
                        "message": "The flow client request error rate has reached the 5% threshold in the last 60 minutes. A higher error rate will make it harder for users to complete the flow, resulting in drop-offs.",
                        "flow_id": "691244242662581",
                        "error_rate": 14.28,
                        "threshold": 10,
                        "alert_state": "ACTIVATED",
                        "errors": [
                            {
                                "error_type": "INVALID_SCREEN_TRANSITION",
                                "error_rate": 66.66,
                                "error_count": 2
                            },
                            {
                                "error_type": "PUBLIC_KEY_MISSING",
                                "error_rate": 33.33,
                                "error_count": 1
                            }
                        ]
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

ENDPOINT_ERROR_RATE

El campo event es "ENDPOINT_ERROR_RATE".

Ejemplo

Ejemplo completo de ENDPOINT_ERROR_RATE:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "ENDPOINT_ERROR_RATE",
                        "message": "The flow endpoint request error rate has reached the 10% threshold in the last 30 minutes. A higher error rate will make it harder for users to complete the flow, resulting in drop-offs.",
                        "flow_id": "691244242662581",
                        "error_rate": 14.28,
                        "threshold": 10,
                        "alert_state": "ACTIVATED",
                        "errors": [
                            {
                                "error_type": "CAPABILITY_ERROR",
                                "error_rate": 66.66,
                                "error_count": 2
                            },
                            {
                                "error_type": "TIMEOUT",
                                "error_rate": 33.33,
                                "error_count": 1
                            }
                        ]
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

ENDPOINT_LATENCY

El campo event es "ENDPOINT_LATENCY".

Ejemplo

Ejemplo completo de ENDPOINT_LATENCY:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "ENDPOINT_LATENCY",
                        "message": "Flow endpoint latency has reached the p90 threshold in the last 30 minutes. High latency will increase the loading time between screens in the flow, impacting user experience.",
                        "flow_id": "691244242662581",
                        "p90_latency": 8000,
                        "p50_latency": 500,
                        "requests_count": 34,
                        "threshold": 7000,
                        "alert_state": "ACTIVATED"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

ENDPOINT_AVAILABILITY

El campo event es "ENDPOINT_AVAILABILITY".

Ejemplo

Ejemplo completo de ENDPOINT_AVAILABILITY:

{
    "entry": [
        {
            "id": "106181168862417",
            "time": 1674160476,
            "changes": [
                {
                    "value": {
                        "event": "ENDPOINT_AVAILABILITY",
                        "message": "The flow endpoint availability has breached the 90% threshold in the last 10 minutes. Users will be unable to open or use the flow.",
                        "flow_id": "12345678",
                        "alert_state": "ACTIVATED",
                        "availability": 75,
                        "threshold": 90
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

Advertencia de congelación o expiración de la versión del Flow

Se envía cuando una versión del Flow está por congelarse o expirar, para que migres a la versión recomendada antes de perder la capacidad de publicar o enviar el Flow. Hay dos casos:

Al crear un Flow, si una versión en uso está por congelarse: un evento FLOW_STATUS_CHANGE que además incluye un campo warning.
Cuando envías un Flow cuya versión está por expirar: un evento dedicado FLOW_VERSION_EXPIRY_WARNING. WhatsApp procura enviar solo uno de estos por cada Flow afectado.

Ejemplo

Ejemplo completo de Advertencia de congelación o expiración de la versión del Flow:

Advertencia de congelación al crear un Flow

{
    "entry": [
        {
            "id": "644600416743275",
            "time": 1684969340,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_STATUS_CHANGE",
                        "message": "Flow Webhook 3 has been created with DRAFT status",
                        "flow_id": "6627390910605886",
                        "new_status": "DRAFT",
                        "warning": "Your current Flow version will freeze in 21 days. You won't be able to send the Flow after it expires. Please migrate to the recommended version as soon as possible."
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

Advertencia de expiración de la versión

{
    "entry": [
        {
            "id": "644600416743275",
            "time": 1684969340,
            "changes": [
                {
                    "value": {
                        "event": "FLOW_VERSION_EXPIRY_WARNING",
                        "warning": "Your current Flow version will freeze in 21 days. You won't be able to send the Flow after it expires. Please migrate to the recommended version as soon as possible.",
                        "flow_id": "6627390910605886"
                    },
                    "field": "flows"
                }
            ]
        }
    ],
    "object": "whatsapp_business_account"
}

Whatsapp — Anterior

Notificaciones de grupos

Siguiente — Whatsapp

Payments Brasil