Centro de ayuda Compatibilidad de la API de Mensaje

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:

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

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
```

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.

<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.

Resultados de búsqueda

Compatibilidad de la API de Mensaje

Configuración de conexión

Autenticación y credenciales

Tipos de mensajes de Viber

Formato de respuesta

Respuesta aceptada (éxito)

Respuestas de error

Devoluciones de llamada

1. Devolución de llamada del estado de entrega

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

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