Centro de ayuda Compatibilidad API de GMS

Compatibilidad API de GMS

SMSBAT admite una capa de compatibilidad con GMS API. Esto le permite migrar sus integraciones existentes diseñadas para GMS directamente a SMSBAT sin tener que modificar sus esquemas de enrutamiento de mensajes, estructuras de carga útil o escuchas de devolución de llamadas.

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/GMSMessage/send_message
Formato de solicitud: aplicación/json
Autenticación: Autenticación básica HTTP (utiliza sus credenciales de API SMSBAT)

Parámetros de solicitud

La API de compatibilidad de GMS acepta un objeto JSON con los siguientes parámetros de nivel superior:

Parámetro	Tipo	Requerido	Descripción
`número_teléfono`	cadena	Sí	Número de teléfono del destinatario en formato internacional (por ejemplo, “380501234567”).
`etiqueta`	cadena	Sí	Nombre del remitente registrado/nombre alfa.
`canales`	matriz	Sí	Lista de canales para probar, en orden de prioridad. Valores admitidos: `viber`, `sms`, `push`. Por ejemplo, `["viber", "sms"]`.
`opciones_canal`	objeto	Sí	Mapa que contiene opciones para cada canal activo (ver más abajo).
`extra_id`	cadena	No	Su ID de mensaje interno del lado del cliente.
`url_devolución de llamada`	cadena	No	URL del punto final en su sistema para recibir devoluciones de llamadas sobre el estado de entrega.
`código_división`	cadena	No	Identificador de código de división opcional (por defecto “principal”).

Configuración de opciones de canal

El objeto channel_options contiene configuraciones específicas del canal.

Se utiliza cuando “viber” aparece en la lista de “canales”.

Parámetro	Tipo	Requerido	Descripción
`texto`	cadena	Sí	Texto del cuerpo del mensaje.
`ttl`	entero	Sí	Tiempo de vida en segundos.
`img`	cadena	No	URL HTTPS pública de la imagen que se mostrará.
`título`	cadena	No	Etiqueta de texto del botón.
`acción`	cadena	No	URL de destino cuando se hace clic en el botón.
`opciones_encuesta`	matriz	No	Matriz de cadenas (de 2 a 5 elementos) para mostrar como opciones de encuesta.
`carrusel_items`	matriz	No	Conjunto de objetos de diapositivas para mostrar como un carrusel de Viber (ver estructura en la pestaña).

Ejemplo de solicitud de Viber:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

Habilita la mensajería de Viber con un respaldo automático de SMS si la entrega de Viber falla dentro del TTL.

Ejemplo de solicitud de respaldo:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Se utiliza cuando sms aparece en la lista de canales.

Parámetro	Tipo	Requerido	Descripción
`texto`	cadena	Sí	Texto del cuerpo del mensaje.
`nombre_alfa`	cadena	Sí	Nombre alfabético del remitente.
`ttl`	entero	Sí	Tiempo de vida en segundos.
`ctr`	booleano	No	Habilite el seguimiento de clics CTR en enlaces de texto (`verdadero`/`falso`).

Ejemplo de solicitud de SMS:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Se utiliza para crear encuestas y sondeos de Viber.

Warning

La configuración de la encuesta de Viber debe tener entre 2 y 5 opciones dentro de survey_options.

Ejemplo de solicitud de encuesta:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

Se utiliza para enviar tarjetas de diapositivas con imágenes deslizables. Cada diapositiva admite imágenes, títulos y botones.

Ejemplo de solicitud de carrusel:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Choose an offer",
      "ttl": 60,
      "carousel_items": [
        {
          "title": "Offer 1",
          "image_url": "https://www.example.com/offer-1.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-1",
          "secondary_label": "More",
          "secondary_url": "https://www.example.com/offers"
        },
        {
          "title": "Offer 2",
          "image_url": "https://www.example.com/offer-2.png",
          "primary_label": "Open",
          "primary_url": "https://www.example.com/offer-2"
        }
      ]
    }
  }
}

Se utiliza cuando push aparece en la lista de channels.

Parámetro	Tipo	Requerido	Descripción
`título`	cadena	Sí	Texto del título de la notificación push.
`texto`	cadena	Sí	Texto del cuerpo del mensaje.
`ttl`	entero	Sí	Tiempo de vida en segundos.
`img`	cadena	No	URL HTTPS pública de la imagen que se mostrará.
`título`	cadena	No	Etiqueta de texto del botón.
`acción`	cadena	No	URL de destino cuando se hace clic en el botón.
`ctr`	booleano	No	Habilite el seguimiento de clics.

Ejemplo de solicitud push:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

Formato de respuesta

El punto final devuelve respuestas en formato JSON con un código de estado “HTTP 200 OK”.

Respuesta exitosa

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

Respuestas de error

Si la validación o el procesamiento fallan, se devolverá una respuesta de error con un “ErrorCode” no nulo y un “ErrorText” detallado.

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

Formato de entrega de devolución de llamada

Si se especificó callback_url en la solicitud, SMSBAT envía actualizaciones del estado de entrega como una carga útil JSON POST a su punto final.

Ejemplo de solicitud de devolución de llamada

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

Descripción de los campos de devolución de llamada

Campo	Tipo	Descripción
`número`	cadena	Número de teléfono del destinatario.
`tiempo`	número	Marca de tiempo del evento en milisegundos de Unix.
`estado`	número	Identificador de estado simplificado (ver tabla de códigos de estado).
`subestado`	número	Identificador de estado detallado (consulte la tabla de códigos de subestado).
`hyber_status`	número	Código de estado interno SMSBAT detallado (consulte la tabla de estado de Hyber).
`id_mensaje`	cadena	ID de mensaje SMSBAT (GUID) generado en el envío.
`extra_id`	cadena	ID del lado del cliente proporcionado en la solicitud original.
`enviado_via`	cadena	Canal que procesó el mensaje: `viber`, `sms` o `rcs`.
`matching_template_id`	número	Estado de coincidencia de la plantilla de Viber (cuando corresponda).

Asignaciones de estado

1. Estado simplificado (`status`)

Código	Significado
`1`	Mensaje aceptado o en proceso de entrega.
`2`	Mensaje entregado.
`3`	Error de procesamiento o entrega.

2. Estado detallado (`subestado`)

Código	Significado
`12`	Aceptado para su procesamiento.
`23`	Entregado.
`24`	Visto/leído.
`35`	No entregado dentro de TTL (caducado).
`36`	Error de entrega.

3. Tipo de canal (`sent_via`)

Canal	Descripción
`vibrador`	Estado producido por el canal Viber.
`sms`	Estado producido por el canal SMS.
`rcs`	Estado producido por el canal RCS.

4. Estado detallado de SMSBAT (`hyber_status`)

Código	Canal	Estado	Subestado	Significado
23033	`vibrador`	`2`	`23`	Mensaje de Viber entregado.
24013	`vibrador`	`2`	`24`	Mensaje de Viber leído por el destinatario (Visto).
36013	`vibrador`	`3`	`36`	Error interno de Viber.
36023	`vibrador`	`3`	`36`	ID de servicio Viber no válido o no disponible.
36033	`vibrador`	`3`	`36`	Datos de carga útil de Viber no válidos.
36037	`vibrador`	`3`	`36`	La URL de la imagen de Viber es demasiado larga.
36038	`vibrador`	`3`	`36`	URL de imagen de Viber no válida.
36039	`vibrador`	`3`	`36`	Texto de Viber demasiado largo.
36044	`vibrador`	`3`	`36`	Texto de Viber vacío.
36053	`vibrador`	`3`	`36`	Tipo de mensaje de Viber no admitido.
36063	`vibrador`	`3`	`36`	Parámetros de Viber no válidos.
36073	`vibrador`	`3`	`36`	Tiempo de espera del proveedor de Viber.
36083	`vibrador`	`3`	`36`	Remitente de Viber bloqueado por el destinatario.
36093	`vibrador`	`3`	`36`	El destinatario no está registrado como usuario de Viber.
36103	`vibrador`	`3`	`36`	No se encontró ningún dispositivo Android/iOS compatible con Viber.
36113	`vibrador`	`3`	`36`	Dirección IP no autorizada para envío de Viber.
36123	`vibrador`	`3`	`36`	Se detectó un mensaje duplicado de Viber.
36143	`vibrador`	`3`	`36`	Error de facturación de Viber.
36153	`vibrador`	`3`	`36`	Mensaje bloqueado por la lista negra de la plataforma.
36163	`vibrador`	`3`	`36`	Error de procesamiento interno de la plataforma Viber.
36173	`vibrador`	`3`	`36`	Etiqueta de Viber incorrecta o faltante.
36183	`vibrador`	`3`	`36`	Valor TTL de Viber no válido.
12011	`sms`/`rcs`	`1`	`12`	Se aceptan SMS/RCS.
36011	`sms`/`rcs`	`1`	`12`	SMS/RCS en ruta.
23011	`sms`/`rcs`	`2`	`23`	SMS/RCS entregados.
35015	`sms`/`rcs`	`3`	`35`	SMS/RCS caducó (no entregado dentro de TTL).
36021	`sms`/`rcs`	`3`	`36`	Mensaje SMS/RCS eliminado.
36031	`sms`/`rcs`	`3`	`36`	No se pueden entregar SMS/RCS.
36041	`sms`/`rcs`	`3`	`36`	Estado de entrega de SMS/RCS desconocido.
36051	`sms`/`rcs`	`3`	`36`	Mensaje SMS/RCS rechazado.

Resultados de búsqueda

Compatibilidad API de GMS

Configuración de conexión

Parámetros de solicitud

Configuración de opciones de canal

Formato de respuesta

Respuesta exitosa

Respuestas de error

Formato de entrega de devolución de llamada

Ejemplo de solicitud de devolución de llamada

Descripción de los campos de devolución de llamada

Asignaciones de estado

1. Estado simplificado (status)

2. Estado detallado (subestado)

3. Tipo de canal (sent_via)

4. Estado detallado de SMSBAT (hyber_status)

1. Estado simplificado (`status`)

2. Estado detallado (`subestado`)

3. Tipo de canal (`sent_via`)

4. Estado detallado de SMSBAT (`hyber_status`)