API de devolución de llamada

Visión general

Los datos de "estado del mensaje" y "respuesta del mensaje" se devuelven mediante callback al sistema empresarial de la empresa, y esta información se puede utilizar para realizar acciones como estadísticas y respuesta a usuarios.

Dirección de callback

Las empresas deben configurar direcciones de callback para recibir el estado del mensaje y la respuesta del mensaje. Para obtener más información, consulte configuración de callback.

Formato de callback

El método de solicitud es POST, el cuerpo de la solicitud es JSON y el tipo de datos es "Content-Type: application/json"
Se devuelven varios registros de datos a la vez.

Mecanismo de seguridad

Próximamente. En la actualidad, el callback no contiene información de autenticación, por lo que no se debe configurar verificación de permisos para la API con la que el desarrollador recibe el callback.

Mecanismo de respuesta

Después de recibir el callback de Engagelab, el servicio del desarrollador debe responder en un plazo de 3 segundos de la siguiente manera:
recepción correcta: el código de estado de la respuesta HTTP debe devolver 200 y no se requiere ningún mensaje de respuesta.

Mecanismo de reintento

Próximamente.

Parámetros de solicitud

Los parámetros de solicitud de EngageLab a la dirección de callback del sistema empresarial son los siguientes:

Campo	Tipo	Opción	Descripción
total	int	required	Volumen de datos del callback
rows	JSON Array	required	Detalles del callback

Los parámetros de rows son los siguientes:

Campo	Tipo	Opción	Descripción
message_id	string	optional	Estado del mensaje y respuesta.
from	string	optional	Remitente; se devuelve cuando se envía el mensaje ascendente en el estado del mensaje.
to	string	optional	Destinatario; estado del mensaje y mensaje ascendente.
server	string	required	Servicio de producto al que pertenece la información del callback. El valor fijo es whatsapp.
channel	string	optional	Canal al que pertenece el estado o la respuesta. El valor fijo es whatsapp
itime	int	required	Marca de tiempo generada por los datos del callback. Se puede utilizar el campo message_status para obtener la marca de tiempo de la solicitud, la marca de tiempo de envío, la marca de tiempo de entrega y la marca de tiempo de lectura.
custom_args	JSON Object	optional	Campos opcionales personalizados al enviar el mensaje, que se devuelven como se indica a continuación en el callback de estado del mensaje.
status	JSON Object	optional	Campo de estado del mensaje
response	JSON Object	optional	Campos de respuesta del mensaje

Estado del mensaje (status)

Parámetros de callback

Campo	Tipo	Opción	Descripción
message_status	string	required	Estado del mensaje.
status_data	JSON Object	optional	Datos detallados de este estado
error_code	int	optional	Código de error. Si se produce un fallo, se devuelve el código de error.
error_detail	JSON Object	optional	Detalles del error. Si se produce un fallo, se devuelve el mensaje de error.
loss	JSON Object	optional	Etapa de pérdida y origen de la pérdida

Respuesta de message_status

Valor	Descripción	Definición
plan	envío programado	El número está dentro del "número de destinatarios" para registrar el estado de un objetivo de envío planificado.
target_valid	objetivo válido	Supera la verificación de validez 1. EngageLab determina que el número es válido. 2. El servicio de Meta WhatsApp determina que el número es válido.
sent	enviado correctamente	El mensaje de error devuelto después de que EngageLab envía el número al servicio de Meta WhatsApp.
delivered	entregado correctamente	El servicio de Meta WhatsApp confirma que el mensaje se ha entregado al usuario.
read	leído	El servicio de Meta WhatsApp confirma que el usuario ha leído el mensaje.
target_invalid	el objetivo no es válido	1. EngageLab determina que el número no es válido. 2. El servicio de Meta WhatsApp determina que el número no es válido.
sent_failed	error al enviar	Mensaje de error devuelto después de que el número se envía al servicio de Meta WhatsApp.
delivered_failed	error de entrega	El número se envió al servicio de Meta WhatsApp, pero el callback de Meta falló.
delivered_timeout	no entregado tras el tiempo de espera	El número se envió correctamente al servicio de Meta WhatsApp, pero Meta no devolvió el callback en 5 minutos para indicar si se realizó correctamente o no; se contabiliza como tiempo de espera.

status_data

Campo	Tipo	Opción	Descripción
msg_time	int	required	Hora a la que se envió el mensaje.
channel_message_id	String	required	ID del mensaje devuelto por WhatsApp.
whatsapp_business_account_id	String	required	ID de la cuenta de WhatsApp Business a la que pertenece el número de envío.
timezone	String	required	Zona horaria de la organización
plan_user_total	int	optional	Número total de objetivos planificados. Este valor solo está disponible cuando message_status = plan.
country_code	String	required	Código de país del número de teléfono móvil del destinatario.
from_phone_id	String	required	ID del número de envío (from)
conversation	JSON Object	optional	Información de la sesión
pricing	JSON Object	optional	Información de precios

conversation

Campo	Tipo	Opción	Descripción
id	String	optional	ID de la conversación de Meta a la que pertenece el mensaje.
origin	JSON Object	optional	Indica quién inició la conversación. Se especifica mediante type. Ejemplo: "origin":{"type":"business_initiated"}. Valores válidos: business_initiated: indica que la conversación comienza cuando la empresa envía el primer mensaje al cliente. Esto se aplica a cualquier momento posterior a 24 horas desde el último mensaje del cliente. customer_initiated: indica que la conversación comienza cuando la empresa responde al mensaje del cliente. Esto solo se aplica cuando la respuesta de la empresa se realiza dentro de 24 horas desde el último mensaje del cliente. referral_conversion: indica que la conversación se origina desde un punto de entrada gratuito. Estas conversaciones siempre son iniciadas por clientes.

pricing

Campo	Tipo	Opción	Descripción
pricing_model	String	optional	Valor fijo: CBP
category	String	optional	Categoría de tarificación de la conversación. Valores válidos: business_initiated: conversación de la empresa. customer_initiated: conversación del usuario. referral_conversion: conversación de punto de acceso gratuito.

error_detail

Campo	Tipo	Opción	Descripción
message	String	required	Causa

loss

Campo	Tipo	Opción	Descripción
loss_step	int	required	Fase de pérdida 1: de objetivo planificado a objetivo efectivo; es decir, objetivo no válido 2: objetivo válido ~ envío; es decir, error al enviar 3: de envío a entrega; error de entrega
loss_source	String	required	Origen de la pérdida. Valores válidos: engagelab: pérdida de EngageLab WhatsApp causada por verificación del servicio meta: error devuelto por Meta.

Ejemplo de callback

{"total":1,"rows":[...]}

              
              {"total":1,"rows":[...]}

Este bloque de código se muestra en una ventana flotante

Respuesta del mensaje

Parámetros de callback

Campo	Tipo	Opción	Descripción
event	string	optional	Evento de respuesta
response_data	JSON Object	optional	Contenido del mensaje de respuesta/interacción ascendente

event

Valor	Descripción	Detalles
received	mensajes de usuario recibidos	El usuario envió un mensaje directamente.
reply	el usuario respondió a su mensaje	La empresa envía primero un mensaje al usuario y el usuario decide responder al mensaje.
order	pedidos del usuario	-
deleted	el usuario eliminó su mensaje	El usuario eliminó el mensaje enviado por sí mismo (próximamente)

response_data

Campo	Tipo	Opción	Descripción
channel_message_id	String	required	ID del mensaje devuelto por WhatsApp.
whatsapp_business_account_id	String	required	ID de la cuenta de WhatsApp Business a la que pertenece el número de envío.
contact	JSON Object	optional	Información del remitente
message	JSON Object	required	Contenido del mensaje
message_context	JSON Object	Optional	Contexto del mensaje; aparece en el evento reply e indica a qué mensaje respondió el usuario

contact

Campo	Tipo	Opción	Descripción
profile	JSON Object	optional	Información del remitente (cliente). Actualmente, solo el campo name indica el nombre del cliente. Ejemplo: "profile": {"name": "bob"}
wa_id	String	optional	Número del remitente.

message

Campo	Tipo	Opción	Descripción
type	String	required	Valores válidos: text, image, audio, video, document, sticker, button, interactive, unknown y order.
text	JSON Object	optional	Para más información, consulte descripción del objeto text
image	JSON Object	optional	Para más información, consulte descripción del objeto image
audio	JSON Object	optional	Para más información, consulte descripción del objeto audio
video	JSON Object	optional	Para más información, consulte descripción del objeto video
document	JSON Object	optional	Para más información, consulte descripción del objeto document
sticker	JSON Object	optional	Para más información, consulte descripción del objeto sticker

message_context

Campo	Tipo	Opción	Descripción
origin_from_phone	String	Required	Número de envío del mensaje referenciado; tenga en cuenta que aquí no hay espacios ni símbolos +
origin_channel_message_id	String	Required	ID único del mensaje referenciado
origin_from_phone_id	String	Optional	ID del número de envío del mensaje referenciado; normalmente incluye este campo
origin_message_id	String	Optional	ID del mensaje referenciado; normalmente incluye este campo

Ejemplo de callback

{"total":1,"rows":[...]}

              
              {"total":1,"rows":[...]}

Este bloque de código se muestra en una ventana flotante

Notificación de mensajes - Notification

Parámetros de callback

Campo	Tipo	Opción	Descripción
event	string	Optional	Evento de respuesta
notification_data	JSON Object	Optional	Contenido específico de la notificación de mensaje del sistema

event

Valor	Descripción	Explicación detallada
insufficient_balance	Saldo insuficiente	El saldo en tiempo real está por debajo del umbral configurado (el valor predeterminado es 10 USD)
template_update	Se cambió el estado de la plantilla	Cambio de estado de la plantilla y cambio de calidad de la plantilla
phone_number_update	Se cambió el estado del número de envío	Cambio de estado del número de envío; actualmente, el oficial solo admite cambios de "límite de envío de mensajes".
whatsapp_business_update	Se cambió la cuenta de WABA	Cuenta WABA bloqueada, advertida, etc.

Ejemplo de callback

{"total":1, "rows":[{ "server": "whatsapp", "itime":1640707579, "notification":{ "event":"insufficient_balance", "notification_data":{ "whatsapp_business_account_id":"", "remain_balance": 5.1234, "balance_threshold": 10 } } }] }

              
              {"total":1, 
  "rows":[{
  "server": "whatsapp", 
  "itime":1640707579,
  "notification":{
      "event":"insufficient_balance",
    "notification_data":{
      "whatsapp_business_account_id":"",
      "remain_balance": 5.1234,					
      "balance_threshold": 10
    }
  }
}]
}

Este bloque de código se muestra en una ventana flotante