Interfaz de callback de estado del ciclo de vida

Este documento describe la estructura de datos y los campos de la interfaz de callback de estado del ciclo de vida de los mensajes. El sistema realiza un callback de la información de estado a la URL configurada por el cliente, mediante HTTP POST, cuando cambia el estado del mensaje.

Forma del callback

• Método de solicitud: POST
• Content-Type: application/json
• Respuesta de éxito: código de estado HTTP 200 o 204
• Reintento en caso de fallo: si el cliente no devuelve un código de estado de éxito, el sistema reintentará automáticamente

Estructura de datos

1. Estructura externa (ReportLifecycles)

              
              {
  "total": 1,
  "rows": [
    {
      // array de objetos ReportLifecycle
    }
  ]
}

            

2. Objeto ReportLifecycle

Cada elemento del array rows tiene la siguiente estructura:

3. Objeto Status

Objeto con la información detallada del estado:

Nota: los siguientes campos son de uso estadístico interno y no se incluyen en el callback al cliente:

• analysis - campo de análisis estadístico interno

4. Objeto StatusData

Datos básicos relacionados con el estado:

Nota: los siguientes campos son información sensible o campos internos; se han filtrado y no se incluyen en el callback al cliente:

• message_content - contenido del mensaje (información sensible)
• parts - número de fragmentos del mensaje (campo interno)
• msg_type - tipo de mensaje (campo interno)
• protocol_type - tipo de protocolo (campo interno)
• supplier_ids - ID del proveedor (información sensible)

5. Objeto Billing

Información de facturación (se devuelve solo cuando hay datos de facturación):

Nota: los siguientes campos son campos de facturación internos y no se incluyen en el callback al cliente:

• cost10000 - campo de facturación interno (en unidades de diezmilésimas)
• sender_cost10000 - coste del remitente (en unidades de diezmilésimas)

6. Objeto ErrorDetail

Detalles del error (se devuelve solo cuando se produce un error):

7. Objeto KwaiExtra

Información de extensión específica para clientes de Kwai (se devuelve solo en el estado de entrega y cuando se trata de un cliente de Kwai):

Descripción de los estados del mensaje

Valores de estado del mensaje habituales:

Ejemplos de callback

Ejemplo 1: mensaje entregado correctamente

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "delivered",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}

            

Ejemplo 2: error al enviar el mensaje

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number",
          "channel_code": "INVALID_NUMBER",
          "channel_message": "The phone number format is invalid"
        }
      }
    }
  ]
}

            

Ejemplo 3: error de entrega del mensaje (con información de facturación)

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456791",
      "to": "+6598765434",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234570,
      "custom_args": {
        "campaign": "new_year_promo"
      },
      "status": {
        "message_status": "delivered_fail",
        "status_data": {
          "msg_time": 1701234562,
          "message_id": "123456791",
          "current_send_channel": "CHANNEL_C",
          "template_key": "marketing",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.0045,
          "currency": "USD"
        },
        "error_code": 5002,
        "error_detail": {
          "message": "Phone number unreachable",
          "channel_code": "UNREACHABLE",
          "channel_message": "Subscriber absent"
        }
      }
    }
  ]
}

            

Ejemplo 4: entrega de mensaje de voz a cliente de Kwai

              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456792",
      "to": "+6598765435",
      "server": "voice",
      "channel": "voice",
      "itime": 1701234575,
      "status": {
        "message_status": "delivered",
        "status_data": {
          "msg_time": 1701234565,
          "message_id": "123456792",
          "current_send_channel": "VOICE_CHANNEL_A",
          "template_key": "voice_verify",
          "business_id": "2001"
        },
        "billing": {
          "cost": 0.012,
          "currency": "USD"
        },
        "error_code": 0,
        "kwai_extra": {
          "delivered_time": 1701234575000,
          "parts": 1,
          "duration": 45
        }
      }
    }
  ]
}

            

Aspectos importantes

1. Reglas de devolución de campos

   • Todos los campos marcados como omitempty no aparecen en el JSON devuelto cuando su valor es vacío o cero
   • La información sensible y los campos internos se filtran o se vacían antes del callback

2. Seguridad

   • El contenido del mensaje (message_content) no se incluye en el callback al cliente
   • La información sensible, como el ID del proveedor (supplier_ids), se ha filtrado
   • Los campos de facturación internos (cost10000, sender_cost10000) no se incluyen en el callback

3. Requisitos de recepción

   • El endpoint de callback del cliente debe devolver una respuesta en un plazo de 5 segundos
   • Debe devolver el código de estado HTTP 200 o 204 para indicar que la recepción fue correcta
   • Si devuelve otro código de estado o se agota el tiempo de espera, el sistema reintentará automáticamente

4. Mecanismo de reintento

   • Tras un fallo del callback, se reintentará automáticamente
   • El intervalo entre reintentos aumenta progresivamente
   • Durante los reintentos, los datos se guardan en Redis

5. Acerca de las marcas de tiempo

   • itime: marca de tiempo en la que se produce el callback, en segundos
   • msg_time: marca de tiempo de creación del mensaje, en segundos
   • delivered_time: campo específico de Kwai, marca de tiempo de entrega, en milisegundos

6. Parámetros personalizados

   • El campo custom_args devuelve tal cual los parámetros personalizados pasados al enviar el mensaje
   • Si al enviar no se pasaron parámetros personalizados, este campo no aparece en los datos del callback

Referencia de códigos de error

Descripción de los códigos de error habituales (para los códigos de error concretos, consulte la documentación de códigos de error):

Para una descripción más detallada de los códigos de error, consulte la documentación específica de códigos de error.

Registro de cambios

• 2024-01: versión inicial
• Se añadió el campo kwai_extra para dar soporte a los clientes de Kwai
• Se filtraron los campos de información sensible para reforzar la seguridad