Notificaciones de estatus

Last update: 4 days ago by Irais Aguirre

Resumen para integración
Entrega: WhatsApp → Concepto Móvil → POST a la URL de tu webhook (la que compartes con nuestro equipo de Operaciones), con un JSON en el cuerpo.
Formato: el objeto value de Meta sin metadata ni messaging_product (ver Webhook).
Identificar al usuario: from/recipient_id o, si no llega, el BSUID.
Tipos en esta página: estatus sent, delivered, read, failed y deleted (valores de status)

Estatus de los mensajes que enviaste. Llegan en el arreglo statuses. Para los estatus de mensajes enviados a un grupo, consulta Estatus de mensajes enviados a un grupo.

Estatus de mensajes

Llega cada vez que cambia el estatus de un mensaje enviado: sent, delivered, read, failed o deleted.

Estructura

Campos de Estatus de mensajes:

Nombre	Descripción	Tipo	Requerimientos
id	Id interno del mensaje (el id devuelto por la API de envío).	String	Obligatorio.
recipient_id	Teléfono al que se le envió el mensaje. No llega si el mensaje se envió al BSUID y el número no está disponible.	String	Condicional
recipient_user_id	BSUID del destinatario. Siempre llega, excepto en el estatus failed de un mensaje enviado al número de teléfono.	String	Condicional
recipient_parent_user_id	BSUID principal del destinatario. Solo llega si el negocio tiene portafolios vinculados.	String	Opcional
type	Tipo de estatus (p. ej. "payment").	String	Opcional
status	Los estatus del mensaje son: sent: mensaje enviado delivered: mensaje entregado read: mensaje leído failed: el mensaje no se pudo enviar deleted: el usuario eliminó el mensaje	String	Obligatorio.
timestamp	Fecha y hora en la que ocurrió el estatus.	String	Obligatorio
errors	Arreglo con los errores asociados al estatus del mensaje (típicamente para `failed`).	Arreglo de objetos	Opcional
conversation	Atributos de la conversación actual.	Objecto	Opcional. Este dato puede no incluirse en algunas notificaciones
pricing	Atributos de facturación.	Objecto

Las notificaciones de estatus no incluyen el objeto contacts.

Objeto conversation

Nombre	Descripción	Tipo	Requerimientos
id	Identificador de la conversación	String	Obligatorio.
expiration_timestamp	Fecha y hora (epoch) en la que expira la ventana de la conversación.	String	Opcional.
origin	Describe la categoría de conversación. authentication marketing utility service referral_conversion	Objeto	Obligatorio
pricing	Los atributos de facturación pueden venir anidados dentro de `conversation`.	Objeto	Opcional

Objeto origin

Nombre	Descripción	Tipo	Requerimientos
type	- authentication: Indica que la conversación fue abierta por una empresa que envió una plantilla categorizada como mensaje de AUTHENTICATION a un cliente. marketing: Indica que la conversación fue abierta por una empresa que envió una plantilla categorizada como mensaje de MARKETING a un cliente. utility: Indica que la conversación fue abierta por una empresa que envió una plantilla categorizada como mensaje de UTILITY a un cliente. service: Indica que la conversación iniciada por una empresa respondiendo a un cliente dentro de una ventana de servicio al cliente. referral_conversion: Indica un punto de conversación de entrada libre.	String	Obligatorio.

Objeto pricing

Nombre	Descripción	Tipo	Requerimientos
billable	Indica si el mensaje o conversación dado es facturable. El valor varía de acuerdo al pricing_model. CBP: Es false si la conversación se inició desde puntos de entrada gratuitos. Para todas las demás conversaciones es true. También se establece como true para las conversaciones dentro del límite de su nivel gratuito. NBP: Es false para las conversaciones de servicio. Es true para conversaciones de autenticación, marketing y servicios públicos.	Boolean	Obligatorio
pricing_model	Tipo de modelo de precios que se utiliza. Valores admitidos: CBP, NBP y PMP (per-message pricing).	String
type	Tipo de precio (por ejemplo, "regular").	String	Opcional
category	Indica la categoría de precios de la conversación. Valores: business_initiated marketing utility authentication service user_initiated referral_conversion	String
cost	Objeto con el costo del mensaje.	Objeto	Opcional

Objeto cost

Nombre	Descripción	Tipo	Requerimientos
amount	Monto cobrado.	Number	Obligatorio
currency	Moneda del costo.	String	Obligatorio

Objeto errors

Nombre	Descripción	Tipo	Requerimientos
code	Código de error. Para mayor detalle, ver sección Códigos de Error	Number	Obligatorio.
title	Descripción del error	String	Obligatorio
href	Url con mas detalle acerca del error	String	Opcional
details	Detalle adicional del error.	String	Opcional

Ejemplo

Ejemplo completo de Estatus de mensajes:

Notificación exitosa

{
    "statuses": [
        {
            "id": "NTI1NTIwNzc3MDU41qbPgNJ6hLs",
            "status": "delivered",
            "timestamp": "1693419173",
            "recipient_id": "5215520777058",
            "conversation":
            {
                "id": "05b0852529d1652f2ccf3cde096f2150",
                "origin":
                {
                    "type": "service"
                }
            },
            "pricing":
            {
                "billable": true,
                "pricing_model": "CBP",
                "category": "service"
            }
        }
    ]
}

Notificación con código de error

{
    "statuses": [
        {
            "errors": [
                {
                    "code": 470,
                    "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."
                }
            ],
            "id": "gBGGEgZHMlEfAgkM1RBkhDRr7t8", 
            "recipient_id": "12064001000", 
            "status": "failed",
            "timestamp": "1533332775"
        }
    ]
}

Estatus `failed` generado por la plataforma

Cuando Meta rechaza el envío de forma síncrona, la plataforma genera un estatus failed con la siguiente forma. En este caso recipient_id contiene el valor del campo to enviado en la petición (puede ser un BSUID), y no se incluyen recipient_user_id, conversation ni pricing.

{
    "statuses": [
        {
            "id": "NTI1NTIwNzc3MDU41qbPgNJ6hLs",
            "recipient_id": "5215520777058",
            "status": "failed",
            "timestamp": "1693419173",
            "errors": [
                {
                    "code": 1005,
                    "title": "Parameter value is not valid",
                    "details": "Message failed. Invalid parameter."
                }
            ]
        }
    ]
}

Mensaje enviado con BSUID

El mensaje se envió al BSUID del usuario y su número de teléfono no está disponible, así que solo llega recipient_user_id.

{
    "statuses": [
        {
            "id": "NTczMTAyMzQ3NTA51wFDy8kOXTM",
            "status": "sent",
            "timestamp": "1504902988",
            "recipient_user_id": "US.13491208655302741918",
            "recipient_parent_user_id": "US.ENT.506847293015824",
            "conversation": {
                "id": "CONVERSATION_ID",
                "expiration_timestamp": "1504903988",
                "origin": {
                    "type": "marketing"
                }
            },
            "pricing": {
                "billable": true,
                "pricing_model": "PMP",
                "type": "regular",
                "category": "marketing"
            }
        }
    ]
}

Whatsapp — Anterior

Respuestas de mensajes interactivos

Siguiente — Whatsapp

Cambio de número del usuario