En este documento se describe cómo obtener análisis de mensajes, conversaciones y plantillas, como el número de mensajes enviados desde un número de teléfono de empresa, el número de conversaciones y su coste para una cuenta de WhatsApp Business (WABA) o el número de veces que se ha leído una plantilla determinada.
En las respuestas solo se incluirán las métricas de los números de teléfono de empresa y las plantillas asociados con tu cuenta WABA en el momento de la solicitud.
Usa el extremo Cuenta de WhatsApp Business para obtener los análisis.
GET /<WHATSAPP_BUSINESS_ACCOUNT_ID> ?fields=<FIELDS>.<FILTERING_PARAMETER>
Marcador de posición | Descripción | Ejemplo de valor |
---|---|---|
| Obligatorio. Métrica. El valor puede ser uno de los siguientes: |
|
| Obligatorio. Parámetro de filtrado de las métricas. Añade parámetros de filtrado adicionales con puntos. Consulta los valores posibles en las siguientes secciones: |
|
El campo analytics
proporciona el número y el tipo de mensajes enviados y entregados desde los números de teléfono asociados con una cuenta WABA específica. Para conocer las métricas de conversaciones, consulta Análisis de conversaciones. Al llamar a /{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}
, puedes adjuntar los parámetros siguientes.
Nombre | Descripción (Haz clic en la flecha de la columna de la izquierda para consultar las opciones admitidas.) |
---|---|
Tipo: marca de tiempo UNIX | Obligatorio. Fecha de inicio del intervalo de fechas del que estás recuperando los análisis. |
Tipo: marca de tiempo UNIX | Obligatorio. Fecha de finalización del intervalo de fechas del que estás recuperando los análisis. |
Tipo: cadena | Obligatorio. Granularidad con la que quieres recuperar los análisis. |
Tipo: matriz | Opcional. Matriz de números de teléfono de los que quieres recuperar los análisis. Si no se proporciona, se incluyen todos los números de teléfono añadidos a la cuenta WABA. |
Tipo: matriz | Opcional. Tipos de mensajes (mensajes de notificación o mensajes del servicio de atención al cliente) de los que quieres recuperar notificaciones. Proporciona una matriz e incluye |
Tipo: matriz | Opcional. Países de los que quieres recuperar el análisis. Proporciona una matriz con los códigos de país de 2 letras de los países que quieres incluir. Si no se proporciona, se devolverán análisis de todos los países con los que has establecido comunicación. |
Situación: debes obtener el número de mensajes enviados y entregados desde todos los números de teléfono asociados con tu cuenta WABA.
Solución sugerida:Monta la URL a la que quieres llamar e incluye los parámetros de filtración start
, end
y granularity
. A continuación, realiza una solicitud GET
a esa URL:
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-business-account-ID}
?fields=analytics
.start(1543543200)
.end(1544148000)
.granularity(DAY)
&access_token={access-token}"
Una respuesta correcta devuelve un objeto analytics
con los datos que has solicitado:
{ "analytics": { "phone_numbers": [ "16505550111", "16505550112", "16505550113" ], "country_codes": [ "US", "BR" ], "granularity": "DAY", "data_points": [ { "start": 1543543200, "end": 1543629600, "sent": 196093, "delivered": 179715 }, { "start": 1543629600, "end": 1543716000, "sent": 147649, "delivered": 139032 }, { "start": 1543716000, "end": 1543802400, "sent": 61988, "delivered": 58830 }, { "start": 1543802400, "end": 1543888800, "sent": 132465, "delivered": 124392 } # more data points ] }, "id": "102290129340398" }
El campo conversation_analytics
proporciona información sobre conversaciones y costes para una cuenta WABA específica. Al llamar a /{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}
, puedes adjuntar los parámetros siguientes.
Nombre | Descripción (Haz clic en la flecha de la columna de la izquierda para consultar las opciones admitidas.) |
---|---|
Tipo: marca de tiempo UNIX | Obligatorio. Fecha de inicio del intervalo de fechas del que estás recuperando los análisis. |
Tipo: marca de tiempo UNIX | Obligatorio. Fecha de finalización del intervalo de fechas del que estás recuperando los análisis. |
Tipo: cadena | Obligatorio. Granularidad con la que quieres recuperar los análisis. |
Tipo: matriz | Opcional. Matriz de números de teléfono de los que quieres recuperar los análisis. Si no se proporciona, se incluyen todos los números de teléfono añadidos a la cuenta WABA. |
| Opcional. Lista de métricas que te gustaría recibir. Si envías una lista vacía, devolvemos resultados de todos los tipos. |
| Opcional. Lista de categorías de conversaciones. Si envías una lista vacía, devolvemos resultados de todas las categorías de conversaciones. |
| Opcional. Lista de tipos de conversaciones. Si envías una lista vacía, devolvemos resultados de todos los tipos de conversaciones. |
| Opcional. Lista de direcciones de conversaciones. Si envías una lista vacía, devolvemos resultados de todas las direcciones de conversaciones. |
| Opcional. Lista de desgloses que te gustaría aplicar a las métricas. Si envías una lista vacía, devolvemos resultados sin desgloses. |
Los datos de análisis son aproximados y pueden diferir de los mostrados en las facturas debido a pequeñas variaciones en el procesamiento de datos.
A partir de un intervalo de fechas, puedes obtener información de las conversaciones y los costes asociados con tu cuenta WABA. Si quieres, puedes filtrar y desglosar los resultados. Consulta las muestras de código a continuación para obtener ejemplos.
Situación: a partir de un mes determinado, puedes recuperar toda la información de conversaciones y costes de todos los números de teléfono asociados con una cuenta WABA.
Solución sugerida:Monta la URL a la que quieres llamar e incluye los parámetros de filtración que se indican a continuación:
start
: inicio del intervalo de tiempo. En este caso, el principio del mes del que quieres obtener las métricas.end
: final del intervalo de tiempo. En este caso, el final del mes del que quieres obtener las métricas.granularity
: nivel de detalle que quieres que tengan tus puntos de datos. En el ejemplo siguiente, usamos MONTHLY
, de modo que cada punto de datos representa un mes de datos.phone_numbers
: envía una matriz vacía y devolvemos información de todos los números de teléfono asociados con la cuenta WABA.dimensions
: establece esta opción en todos los desgloses disponibles ("CONVERSATION_CATEGORY"
, "CONVERSATION_TYPE"
, "COUNTRY"
y "PHONE"
).En este caso, no tienes que especificar country_codes
, metric_types
, conversation_types
ni conversation_categories
. Si no nos envías nada para estos campos, devolveremos todas las opciones disponibles. Cuando configures la URL, realiza una solicitud GET:
curl -i -X GET
"https://graph.facebook.com/v20.0
/{whatsapp-business-account-id}
?fields=conversation_analytics
.start(1685602800).end(1688194800)
.granularity(MONTHLY)
.phone_numbers([])
.dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
&access_token={access-token}"
Una respuesta correcta devuelve un objeto conversation_analytics
con los datos que has solicitado. En el ejemplo siguiente, la cuenta WABA solo contiene un número de teléfono.
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685602800, "end": 1688194800, "conversation": 1558, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_direction": "UNKNOWN", "conversation_category": "AUTHENTICATION", "cost": 15.58 }, { "start": 1685602800, "end": 1688194800, "conversation": 2636, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_category": "MARKETING", "cost": 26.36 }, { "start": 1685602800, "end": 1688194800, "conversation": 2238, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_category": "SERVICE", "cost": 22.38 }, { "start": 1685602800, "end": 1688194800, "conversation": 1782, "phone_number": "15550458206", "country": "US", "conversation_type": "REGULAR", "conversation_category": "UTILITY", "cost": 17.82 }, { "start": 1685602800, "end": 1688194800, "conversation": 1568, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "AUTHENTICATION", "cost": 15.68 }, { "start": 1685602800, "end": 1688194800, "conversation": 2716, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "MARKETING", "cost": 27.16 }, { "start": 1685602800, "end": 1688194800, "conversation": 2180, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "SERVICE", "cost": 21.8 }, { "start": 1685602800, "end": 1688194800, "conversation": 1465, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_TIER", "conversation_category": "UTILITY", "cost": 14.65 }, { "start": 1685602800, "end": 1688194800, "conversation": 1433, "phone_number": "15550458206", "country": "US", "conversation_type": "FREE_ENTRY_POINT", "conversation_category": "SERVICE", "cost": 14.33 } ] } ] }, "id": "102290129340398", }
Situación: de un intervalo de tiempo determinado, puedes recuperar toda la información de las conversaciones y los costes de un número de teléfono específico asociado con una cuenta WABA. En los resultados, es recomendable utilizar todos los desgloses posibles. Necesitas todos los puntos de datos para representar media hora de datos.
Solución sugerida:Monta la URL a la que quieres llamar e incluye los parámetros de filtración que se indican a continuación:
start
: inicio del intervalo de tiempo. end
: final del intervalo de tiempo.granularity
: nivel de detalle que quieres que tengan tus puntos de datos. En el ejemplo siguiente, usamos HALF_HOUR
, de modo que cada punto de datos representa media hora de datos.phone_numbers
: número de teléfono del que necesitas información.dimensions
: establece esta opción en todos los desgloses disponibles (CONVERSATION_CATEGORY
, CONVERSATION_TYPE
, COUNTRY
y PHONE
).En este caso, no tienes que especificar country_codes
, metric_types
, conversation_types
ni conversation_categories
. Si no nos envías nada para estos campos, devolveremos todas las opciones disponibles. Cuando configures la URL, realiza una solicitud GET:
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-business-account-id}
?fields=conversation_analytics
.start(1685602800)
.end(1685689200)
.granularity(HALF_HOUR)
.phone_numbers(["19195552584"])
.dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
&access_token=your-access-token"
Una respuesta correcta devuelve un objeto conversation_analytics
con los datos que has solicitado:
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685602800, "end": 1685604600, "conversation": 4, "phone_number": "19195552584", "country": "US", "conversation_type": "REGULAR", "conversation_direction": "UNKNOWN", "conversation_category": "SERVICE", "cost": 0.0232 }, { "start": 1685602800, "end": 1685604600, "conversation": 4, "phone_number": "19195552584", "country": "US", "conversation_type": "REGULAR", "conversation_direction": "UNKNOWN", "conversation_category": "MARKETING", "cost": 0.0232 }, # ... more data points ] } ] }, "id": "102290129340398" }
Situación: de un intervalo de tiempo determinado, puedes recuperar toda la información de las conversaciones y los costes de todos los números de teléfono asociados con una cuenta WABA. En los resultados, puedes realizar el desglose por tipo de conversación.
Solución sugerida:monta la URL a la que quieres llamar e incluye los parámetros de filtrado que se indican a continuación:
start
: inicio del intervalo de tiempo. end
: final del intervalo de tiempo.granularity
: nivel de detalle que quieres que tengan tus puntos de datos. En el ejemplo siguiente, usamos MONTHLY
, de modo que cada punto de datos representa medio mes de datos.phone_numbers
: envía una matriz vacía y devolveremos información de todos los números de teléfono asociados con la cuenta WABA.dimensions
: establece esta opción en CONVERSATION_TYPE
.En este caso, no tienes que especificar country_codes
, metric_types
, conversation_types
, conversation_directions
ni conversation_categories
. Si no nos envías nada para estos campos, devolveremos todas las opciones disponibles. Cuando configures la URL, realiza una solicitud GET:
curl -i -X GET
"https://graph.facebook.com/v20.0
/{whatsapp-buiness-account-id}
?fields=conversation_analytics
.start(1643702400).end(1646121600)
.granularity(MONTHLY)
.phone_numbers([])
.dimensions([CONVERSATION_TYPE])
&access_token={access-token}"
Una respuesta correcta devuelve un objeto conversation_analytics
con los datos que has solicitado:
{ "data": [ { "data_points": [ { "start": 1643702400, "end": 1646121600, "conversation": 8500, "conversation_type": "REGULAR", "cost": 88.1010 }, { "start": 1643702400, "end": 1646121600, "conversation”: 1000, "conversation_type": "FREE_TIER", "cost": 0.0000 } { "start": 1643702400, "end": 1646121600, "conversation”: 250, "conversation_type": "FREE_ENTRY_POINT", "cost": 0.0000 } ] } ] }
Solicitud:
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-buiness-account-id}
?fields=conversation_analytics
.start(1685527200)
.end(1685613600)
.granularity(HALF_HOUR)
.conversation_categories(["MARKETING","AUTHENTICATION"])
.dimensions(["CONVERSATION_CATEGORY"])
&access_token={access-token}"
Respuesta:
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685529000, "end": 1685530800, "conversation": 2, "conversation_category": "AUTHENTICATION", "cost": 0.0128 }, { "start": 1685527200, "end": 1685529000, "conversation": 3, "conversation_category": "MARKETING", "cost": 0.0432 } ] } ] }, "id": "102290129340398" }
Solicitud:
curl -i -X GET \
"https://graph.facebook.com/v20.0
/{whatsapp-buiness-account-id}
?fields=conversation_analytics
.start(1685527200)
.end(1685613600)
.granularity(HALF_HOUR)
.conversation_categories(["MARKETING","AUTHENTICATION"])
.dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
&access_token={access-token}"
Respuesta:
{ "conversation_analytics": { "data": [ { "data_points": [ { "start": 1685527200, "end": 1685529000, "conversation": 3, "conversation_type": "REGULAR", "conversation_category": "MARKETING", "cost": 0.0432 }, { "start": 1685529000, "end": 1685530800, "conversation": 2, "conversation_type": "REGULAR", "conversation_category": "AUTHENTICATION", "cost": 0.0128 } ] } ] }, "id": "102290129340398" }
Los análisis de plantillas describen el número de veces que la plantilla se ha enviado, entregado y leído, así como el número de veces que se ha hecho clic en los botones de URL o los botones de respuesta rápida de la plantilla.
Los datos se devuelven con una granularidad diaria en la zona horaria UTC y con un periodo de retrospectiva de 90 días. Los análisis de plantillas también se pueden encontrar en la ventana Administrador de WhatsApp > Plantillas de mensajes > Detalles de la plantilla > Insights.
MARKETING
o UTILITY
.Para notificar errores en los análisis de plantillas, envía un ticket de Asistencia directa con las siguientes selecciones:
Debes confirmar los análisis de plantillas en la cuenta de WhatsApp Business para poder obtener los datos. Puedes confirmar los análisis de plantillas con el Administrador de WhatsApp o la API. Para confirmar los análisis con la API, envía la siguiente solicitud:
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true
Una vez confirmados, empezaremos a capturar los análisis de plantillas de la cuenta de WhatsApp Business. Tras su confirmación, los análisis de plantillas no se pueden desactivar.
Si la operación se realiza correctamente, la API responderá con el identificador de tu cuenta de WhatsApp Business. Por ejemplo:
{ "id": 102290129340398 }
Nombre | Descripción | Ejemplo de valor |
---|---|---|
Marca de tiempo UNIX | Obligatorio. Marca de tiempo de inicio del intervalo de fechas del que estás recuperando los análisis. Como los análisis de plantillas se proporcionan con una granularidad diaria en la zona horaria UTC, una marca de tiempo de inicio distinta de 0:00 UTC se corregiría a la hora 0:00 UTC anterior que correspondiese. |
|
Marca de tiempo UNIX | Obligatorio. Fecha de finalización del intervalo de fechas del que estás recuperando los análisis. Como los análisis de plantillas se proporcionan con una granularidad diaria en la zona horaria UTC, una marca de tiempo de finalización distinta de 0:00 UTC se corregiría a la hora 0:00 UTC siguiente que correspondiese. |
|
Enumeración | Obligatorio. Granularidad con la que quieres recuperar los análisis. El valor debe ser |
|
Matriz de identificadores | Obligatorio. Matriz de identificadores de plantillas de las que quieres recuperar los análisis. Diez como máximo. |
|
Matriz de enumeraciones | Opcional. Las empresas que facturan mediante un socio de soluciones NO pueden acceder al nodo Tipos de métricas que quieres recuperar. Si se omite o se proporciona una matriz vacía, se devolverán los análisis de todos los tipos de métricas. Valores posibles:
Los clics solo se devuelven para los botones de URL y los de respuesta rápida de las plantillas categorizadas como Las métricas de coste se devuelven en forma de matriz de objetos de coste y cada uno tiene un tipo y un valor. A continuación se indican los tipos que pueden ser:
|
|
Situación: teniendo en cuenta un periodo de tiempo de un día, obtén todos los tipos de métricas de análisis de plantillas de una plantilla de autenticación y una de marketing con un botón de URL.
Ejemplo de solicitud:
curl -g 'https://graph.facebook.com/v20.0
/109259195336416/template_analytics?start=1718064000&end=1718122745&granularity=daily&metric_types=cost%2Cclicked%2Cdelivered%2Cread%2Csent&template_ids=[1421988012088524%2C2632273056924580]' \
-H 'Authorization: Bearer EAAJB...'
Ejemplo de respuesta:
{ "data": [ { "granularity": "DAILY", "product_type": "cloud_api", // Only available to businesses in Marketing Messages Lite API alpha "data_points": [ { "template_id": "1421988012088524", "start": 1718064000, "end": 1718150400, "sent": 1, "delivered": 1, "read": 1, "cost": [ { "type": "amount_spent", "value": 0.01 }, { "type": "cost_per_delivered", "value": 0.01 } ] }, { "template_id": "2632273056924580", "start": 1718064000, "end": 1718150400, "sent": 1, "delivered": 1, "read": 1, "clicked": [ { "type": "url_button", "button_content": "Contact Support", "count": 1 } ], "cost": [ { "type": "amount_spent", "value": 0.03 }, { "type": "cost_per_delivered", "value": 0.03 }, { "type": "cost_per_url_button_click", "value": 0.03 } ] } ] } ], "paging": { "cursors": { "before": "MAZDZD", "after": "MjQZD" } } }
Puedes desactivar el seguimiento de los clics en los botones para una plantilla concreta. Para ello, establece el valor del campo cta_url_link_tracking_opted_out
en true
. Una vez desactivado, la API ya no devolverá la propiedad de los clics en los análisis de la plantilla ni mostrará los clics ni la interacción con el botón en el Administrador de WhatsApp al visualizar los insights de la plantilla.
POST /<TEMPLATE_ID> ?cta_url_link_tracking_opted_out=<OPT_OUT> &category=<TEMPLATE_CATEGORY>
Marcador de posición | Descripción | Ejemplo de valor |
---|---|---|
Identificador de la plantilla | Obligatorio. Identificador de la plantilla. |
|
Booleano | Obligatorio. Indica si el seguimiento de los clics en los botones de la plantilla está desactivado. Se establece en El valor se establece en |
|
Cadena | Obligatorio. Categoría actual de la plantilla. Si la categoría de la plantilla se establece en un valor distinto al de la categoría actual, el estado de la plantilla pasará a |
|
curl -X POST 'https://graph.facebook.com/v20.0
/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'
Si la operación se realiza correctamente, la API responderá lo siguiente:
{ "success": true }
Para obtener una lista de todos los valores posibles para cada campo, consulta la referencia de la API Graph del campo Análisis de cuenta de WhatsApp Business.