Saltar a contenido

Guía de API RESTful de SMSBAT

Guía completa de la API RESTful de SMSBAT: todo lo que necesita saber.

Última actualización: 29 de agosto de 2025

SMSBAT RESTful API le permite enviar varios tipos de mensajes: Viber-carrusel, Viber-survey, Viber-promo (imágenes, video), chats comerciales de Viber, mensajes OTP (Viber OTP, Flash Call) y sus variantes alternativas.

Nota: Esta es la API HTTP unificada para mensajería saliente. Si necesita integraciones con bots entrantes (Viber Bot / Telegram Bot), consulte la API de Cascade.

1. Protocolo

  • Protocolo: HTTPS
  • Cuerpo de la solicitud: objeto JSON que contiene una matriz de "mensajes".
  • Métodos:
  • GET para recuperar datos (estado del mensaje, saldo, etc.)
  • POST para crear objetos (por ejemplo, iniciar una transmisión/despacho)
  • PATCH para modificar objetos

2. Autorización

Proporcionamos varios métodos de autorización para su conveniencia: - Autenticación básica HTTP (inicio de sesión y contraseña desde su panel de control). - Encabezado HTTP personalizado X-Authorization-Key que contiene un token API. - Campo de contraseña de autenticación básica HTTP que contiene el token API (pase @ como inicio de sesión).

API Token se puede generar en el Panel de control en Perfil de usuario.

Ejemplos de solicitudes

Con autenticación básica: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

Con X-Clave-de-autorización: 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Envío de mensajes

En la plataforma SMSBAT, cualquier envío de mensaje (incluso un solo mensaje) se considera una "Broadcast" (lista de mensajes).

Punto final - Método: PUBLICAR - URL: https://api.smsbat.com/bat/messagelist - Encabezados: Tipo de contenido: aplicación/json

Estructura de carga útil básica: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Campos obligatorios para cada objeto de mensaje:

  • de: nombre alfa del remitente verificado.
  • to: Número de teléfono del destinatario (formato E.164).
  • tipo: enumeración del tipo de mensaje.
  • text: Texto principal del mensaje (opcional si el tipo no requiere texto).

Valores de "tipo" admitidos: - sms - viber_service (o viber_trans) - viber_promo - viber_carrusel -viber_survey -viber_otp -viber_session -flashcall_callback - llamada flash

Campos comunes opcionales:

  • customerMessageId: ID de cadena dentro de su propio sistema (utilizado para rastrear devoluciones de llamadas). Debe ser único por mensaje.
  • dtSend: ISO8601 Fecha/Hora del envío futuro programado.
  • dtExpire: ISO8601 Fecha/Hora del plazo de entrega.
  • ttl: Tiempo de vida en segundos. (Si no se proporciona dtExpire, la API calcula la asignación predeterminada a partir del tipo).

TTL predeterminados (segundos):

  • sms - 86400 (24h)
  • viber_trans / viber_service - 345600 -viber_promo-604800
  • viber_session - 604800

4. Enrutamiento alternativo (en cascada)

Puede especificar una cola alternativa para garantizar la entrega de mensajes si el canal principal falla o caduca.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
Los respaldos se activan cuando el proveedor rechaza el mensaje principal o cuando expira el TTL.

5. Descripción general de los tipos de mensajes y datos de mensajes

Los tipos de mensajes complejos requieren configuraciones adicionales inyectadas en la propiedad messageData.

5.1 Promoción de Viber (viber_promo)

Solo imagen 

"messageData":{
  "img":"https://domain.com/image.png"
}

Texto + Botón 

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Imagen + Texto + Botón Combina img, buttonText y buttonAction.

Carga útil de vídeo: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(También puedes combinar propiedades de Video con buttonText y buttonAction).

5.2 Transaccional/Servicio de Viber (viber_trans, viber_service)

Si tiene una plantilla aprobada que contiene un archivo adjunto: 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

Requiere una matriz carousel.items dentro de messageData.

Limitaciones: - Longitud de los artículos: entre 2 y 5 artículos - Título: 2 a 38 caracteres - imageUrl: tamaño recomendado JPEG/PNG 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Encuesta/Lista de Viber (viber_survey)

Crea una encuesta interactiva dentro de la vista de chat. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
La propiedad "texto" del mensaje actúa como título de la encuesta (máximo 85 caracteres). Puede pasar entre 2 y 5 opciones, cada una con un máximo de 50 caracteres.

5.5 Viber OTP (viber_otp)

Utiliza plantillas de Viber localizadas previamente registradas a nivel mundial. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Los parámetros de plantilla (pin, business_platform_name) distinguen estrictamente entre mayúsculas y minúsculas. La API admite varias variantes del lenguaje de código ISO (EN, ES, RU, TR, UK, etc.).

5.6 Llamada flash ("flashcall")

Los últimos dígitos del número de marcación (el código generado) deben pasarse a través del parámetro "texto". Si se omite "texto", el código es aleatorio y debe extraerlo del cuerpo de respuesta síncrono 200 OK de la API ("mensajes/texto").

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}