Saltar a contenido

Enviar mensaje

Envíe mensajes a través de la API SMSBAT utilizando el punto final /bat/messagelist.

Punto final

POST /bat/messagelist

Estructura de solicitud

The request body is a JSON array of message objects:

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

Parámetros

Parámetros requeridos

Parámetro Tipo Descripción
de cadena ID de remitente alfanumérico
a cadena Número de teléfono del destinatario en formato E.164 (p. ej., +380XXXXXXXXX)
tipo cadena Tipo de mensaje: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
texto cadena Contenido del mensaje (obligatorio para la mayoría de los tipos, opcional para algunos)

Parámetros opcionales

Parámetro Tipo Descripción
clienteMessageId cadena Su identificador interno para seguimiento
ttl entero Tiempo de vida en segundos
mensajeDatos objeto Configuración específica del tipo (varía según el tipo de mensaje)

Autenticación

Elija uno de los tres métodos de autenticación:

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

Respuesta

Respuesta exitosa

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Campos de respuesta

Campo Tipo Descripción
lista de mensajesId entero Identificador único para la lista de mensajes
Id del mensaje cadena Identificador único para cada mensaje
estado cadena Estado del mensaje: "aceptado", "rechazado", "fallido"
partes entero Número de partes del mensaje (para SMS)
clienteMessageId cadena Su identificador interno (si se proporciona)
a cadena Número de teléfono del destinatario

Tipos de mensajes

SMS

Mensajes de texto simples:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

Promoción de Viber

Mensajes promocionales con rich media:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Transaccional de Viber

Notificaciones de transacciones:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

OTP de Viber

Notificaciones de contraseña de un solo uso:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Manejo de errores

Códigos de estado HTTP

Código Descripción
200 Solicitud exitosa
400 Solicitud incorrecta: parámetros no válidos
401 No autorizado: error de autenticación
429 Demasiadas solicitudes: se superó el límite de tarifa
500 Error interno del servidor

Respuesta de error

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

Mejores prácticas

Formato del número de teléfono

Utilice siempre el formato E.164 para los números de teléfono:

  • ✅ Correcto: +380XXXXXXXXX
  • ❌ Incorrecto: 380XXXXXXXXX, 0XXXXXXXXX

Texto del mensaje

  • Mantenga los SMS con menos de 160 caracteres para evitar múltiples partes
  • Utilice codificación UTF-8 para caracteres internacionales
  • Pruebe los caracteres especiales antes del envío masivo

TTL (tiempo de vida)

  • Establecer TTL apropiado para mensajes urgentes
  • Mensajes OTP: 300-600 segundos (5-10 minutos)
  • Mensajes promocionales: 3600-86400 segundos (1-24 horas)

ID de mensaje del cliente

  • Utilice identificadores únicos para cada mensaje.
  • Ayuda con el seguimiento y la depuración.
  • Útil para correlacionar con los registros de su sistema

Límites de tarifas

Comuníquese con su administrador de cuentas para obtener información sobre:

  • Mensajes por segundo
  • Mensajes por día
  • Conexiones simultáneas

Próximos pasos