Compatibilidad de la API de Mensaje

SMSBAT admite una capa de compatibilidad con Messagio API. Esto le permite migrar sus integraciones de Viber existentes diseñadas para Messagio directamente a SMSBAT sin tener que reescribir su estructura de carga útil ni cambiar la lógica de integración.

Configuración de conexión

Para enrutar solicitudes a través de SMSBAT, actualice la URL base y las credenciales de autenticación en su integración:

URL base: https://restapi.smsbat.com
Punto final: POST /api/SendMessage
Formato de solicitud: application/x-www-form-urlencoded (Datos del formulario)

Autenticación y credenciales

Las solicitudes se autentican utilizando parámetros enviados directamente dentro de los datos del formulario del cuerpo de la solicitud:

Parámetro	Tipo	Requerido	Descripción
`usuario`	cadena	Sí	El inicio de sesión de su cuenta SMSBAT o su identificador de usuario.
`signo`	cadena	Sí	Secreto de API o firma registrada para el nombre del remitente.
`de`	cadena	Sí	Nombre alfabético del remitente registrado.
`método_envío`	cadena	Sí	Tipo de canal. Utilice `viber` para mensajes habituales de Viber Business o `viber_otp` para plantillas Viber OTP.
`teléfono`	cadena	Sí	Número de teléfono del destinatario en formato internacional (por ejemplo, "380501234567").

Tipos de mensajes de Viber

Elija una pestaña a continuación para ver los parámetros específicos y solicitar cargas útiles para diferentes estructuras de mensajes de Viber:

Mensaje de textoTexto + BotónMensaje de imagenTexto + Imagen + BotónMensaje en vídeoPlantilla OTP

Envía un mensaje de texto simple.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`txt`	cadena	Sí	Texto del mensaje.

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Envía un mensaje de texto con un botón interactivo de llamado a la acción.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`txt`	cadena	Sí	Texto del mensaje.
`texto_botón`	cadena	Sí	Texto que se muestra en el botón.
`botón_enlace`	cadena	Sí	URL de destino cuando se hace clic en el botón.

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envía un archivo de imagen pública.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`imagen_enlace`	cadena	Sí	URL HTTPS pública de la imagen.
`txt`	cadena	No	Texto de título opcional para mostrar debajo de la imagen.

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Envía una tarjeta enriquecida que contiene texto, una imagen y un botón.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`txt`	cadena	Sí	Texto del título.
`imagen_enlace`	cadena	Sí	URL HTTPS pública de la imagen.
`texto_botón`	cadena	Sí	Texto que se muestra en el botón.
`botón_enlace`	cadena	Sí	URL de destino cuando se hace clic en el botón.

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envía un archivo de vídeo con un título de texto opcional y botones de acción.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`vídeo.url`	cadena	Sí	URL HTTPS pública del archivo de vídeo.
`video.miniatura`	cadena	Sí	URL HTTPS pública de la imagen de vista previa del vídeo.
`video.tamaño_mb`	entero	Sí	Tamaño aproximado del archivo de vídeo en Megabytes.
`video.duración_sec`	entero	Sí	Duración del vídeo en segundos.
`txt`	cadena	No	Texto de descripción opcional.
`texto_botón`	cadena	No	Texto del botón opcional (puede actuar como título o enlace).
`botón_enlace`	cadena	No	URL del enlace del botón opcional.

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Envía contraseñas de un solo uso (OTP) de Viber utilizando una plantilla previamente aprobada.

Nota

Al enviar mensajes OTP, debe configurar sending_method en viber_otp.

Parámetros adicionales:

| Parámetro | Tipo | Requerido | Descripción |
| :--- | :--- | :--- | :--- |
| `plantilla.id` | cadena | **Sí** | ID de plantilla Viber OTP preaprobada. |
| `plantilla.lang` | cadena | **Sí** | Código de idioma de plantilla (por ejemplo, `en`, `uk`). |
| `plantilla.params.pin` | cadena | **Sí** | El valor del pin OTP para inyectar en la plantilla. |
| `template.params.business_platform_name` | cadena | **Sí** | El marcador de posición del nombre comercial en la plantilla. |
| `template.params.code_validity_time` | cadena | **Sí** | Período de validez del PIN en minutos. |

**Ejemplo de carga útil de solicitud:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

Mensaje del carruselMensaje de encuesta

Envía una tarjeta de mensaje interactiva que contiene varias diapositivas (tarjetas) que el usuario puede deslizar.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`txt`	cadena	Sí	Texto del título del carrusel.
`carrusel[N].título`	cadena	Sí	Título de la tarjeta `N` (comenzando en 0).
`carrusel[N].image_url`	cadena	Sí	URL de imagen HTTPS pública de la tarjeta "N".
`carrusel[N].etiqueta_primaria`	cadena	Sí	Título del botón principal de la tarjeta `N`.
`carrusel[N].primary_url`	cadena	Sí	URL del enlace del botón principal de la tarjeta `N`.
`carrusel[N].etiqueta_secundaria`	cadena	No	Título del botón secundario de la tarjeta `N`.
`carrusel[N].secundaria_url`	cadena	No	URL del enlace del botón secundario de la tarjeta `N`.

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Envía un mensaje que contiene una encuesta interactiva o una pregunta de encuesta.

Parámetros adicionales:

Parámetro	Tipo	Requerido	Descripción
`txt`	cadena	Sí	Texto de la pregunta de la encuesta.
`opciones_encuesta[N]`	cadena	Sí	Texto de opción de encuesta para el elemento `N` (índice que comienza en 0). Se requieren al menos 2 opciones.
`tipo_opción`	entero	Sí	Tipo de selector: `1` (RadioButtons) o `2` (Botones normales).

Ejemplo de carga útil de solicitud:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

Formato de respuesta

El punto final de compatibilidad de la API de Messagio devuelve respuestas en formato XML con un código de estado "HTTP 200 OK".

Respuesta aceptada (éxito)

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Respuestas de error

Si falla la validación de los parámetros de una solicitud o la autenticación, la respuesta devolverá un código distinto de cero.

Falta firmaNo autorizado

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Devoluciones de llamada

Las URL de devolución de llamada deben implementarse y alojarse en su plataforma. SMSBAT envía devoluciones de llamadas HTTP para actualizar su sistema con respecto a eventos de entrega, respuestas a encuestas y respuestas de usuarios.

1. Devolución de llamada del estado de entrega

Se envía cuando un mensaje cambia de estado (entregado, leído, fallido).

Tipo de contenido: aplicación/x-www-form-urlencoded
Método: POST

Solicitar formatos de carga útil:

Entregado:
```
msg_id=MESSAGE_GUID&status=delivered
```

Visto/Leído:

msg_id=MESSAGE_GUID&status=delivered&type=seen

No entregado/Error:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Descripción de campos:

msg_id: ID de mensaje único (GUID) SMSBAT devuelto en la respuesta de SendMessage.
estado: resultado de la entrega (entregado, no entregado o estado desconocido).
tipo: se establece en visto cuando el mensaje ha sido visto por el destinatario.
status_extended: motivo técnico específico del estado no entregado (por ejemplo, VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Devolución de llamada de respuesta a la encuesta

Se activa cuando un usuario selecciona una opción de respuesta en un mensaje de Viber Survey.

Tipo de contenido: aplicación/x-www-form-urlencoded
Método: POST

Solicitar formato de carga útil:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Devolución de llamada de mensaje de usuario entrante

Se activa cuando un usuario envía un mensaje de texto o una respuesta multimedia a su servicio Viber Business.

Tipo de contenido: aplicación/json
Método: POST

Solicitar formato de carga útil:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Descripción de campos:

msg_id: el ID de mensaje único generado para la respuesta entrante.
text: contenido de texto enviado por el usuario (puede ser nulo si solo enviaron medios).
media: URL directa para descargar cualquier archivo adjunto multimedia enviado por el usuario (puede ser nulo si solo es texto).
phone: Número de teléfono del remitente en formato internacional.
sender_bm_id: el ID del remitente de Viber Business.