Solución SMS Personalizada
Integrando una solución/proveedor de SMS personalizado como parte de tu API del Operador
Fast Tracks soporta una variedad de proveedores de SMS, si tu negocio necesita un proveedor que no está en la lista de proveedores soportados, entonces puedes construir esta API.
Servicio de SMS de Fast Track
El servicio de SMS de Fast Track puede ser configurado para enviar solicitudes de SMS a los endpoints de la API del Operador listados abajo, lo que permite al Operador gestionar el proveedor de SMS. Soporta el envío de mensajes y obtener el estado de entrega. El envío está disponible tanto para solicitudes de SMS individuales como por lotes.
Los siguientes endpoints pueden ser construidos como parte de tu API del Operador:
⬆️ POST /channels/sms/single
⬆️ POST /channels/sms/batch
El Operador puede entonces reenviar estas solicitudes al proveedor de SMS para su procesamiento y responder con las respectivas respuestas.
El formato de API y las respuestas necesitan ser formateadas como se describe abajo
Es importante que los datos del "meta" descritos abajo sean enviados de vuelta a Fast Track ya sea por Webhook o Polling para que los datos de conversión puedan ser almacenados correctamente. Por favor, refiere a los ejemplos mostrados y las tablas debajo para mayor clarificación.
Pre-Requisitos
- Avisar a Fast Track si alguna limitación de velocidad debe ser tomada en consideración. (Si planeas implementar limitación de velocidad por favor contacta a Fast Track antes, para que podamos guiarte en la implementación soportada)
- Avisar a Fast Track si algún máximo de lotes debe ser tomado en consideración.
- Proporcionar a Fast Track cualquier credencial específica para los proveedores integrados (si es requerido)
- Los formatos de SMS soportados son GSM7 & USC2
Enviar SMS (Individual)
Una solicitud de envío de SMS individual contendrá los datos de cada SMS individual en solicitudes separadas a la API.
Implementación del Endpoint
Implementa el endpoint en el formato de abajo para soportar SMS de envío individual a través de la API.
⬆️ POST <operator-api-endpoint-url>/channels/sms/single
Header de Solicitud
El header de la solicitud enviada contiene un "X-Api-Key" que es un token requerido para autenticar las llamadas de API en el endpoint. Este token necesita ser pasado a Fast Track para hacer estas solicitudes.
Esquema del Cuerpo de Solicitud
Refiere al siguiente ejemplo de una solicitud de SMS individual enviada por Fast Track. La descripción de cada campo está listada en la tabla debajo de él.
Las propiedades requeridas están marcadas con *
| Clave | Tipo | Descripción |
|---|---|---|
activity.id * | integer | Un identificador único del SMS |
activity.brand_id * | integer | El identificador único de la marca en Fast Track |
activity.user_id * | string | El identificador único del jugador |
activity.activity_id * | integer | El identificador único de la actividad configurada en Fast Track |
activity.action_group_id * | integer | Identificador para el grupo de acción al que pertenece esta actividad |
activity.trigger_hash * | string | Hash que identifica el disparador que activó esta actividad |
activity.action_id * | integer | Identificador para la acción específica dentro de la actividad |
content * | string | El cuerpo del mensaje SMS |
recipient * | string | El número de teléfono del destinatario en formato E.164 |
sender_name * | string | El nombre o número del remitente mostrado al destinatario |
provider_name * | string | El proveedor de SMS por el cual enrutar el mensaje |
encoding * | string | Codificación de caracteres para el mensaje. Valores: auto | gsm7 | ucs2 |
provider_id | string | Identificador de mensaje específico del proveedor (opcional) |
meta | object | Pares clave-valor personalizados definidos en la actividad del CRM de Fast Track |
Respuestas Esperadas
La API del Operador debe retornar las respuestas para cada mensaje SMS individual respectivamente para evitar el almacenamiento no relacionado de datos de SMS.
Exitosa Respuesta JSON HTTP 200-299
El "sms_id" será un identificador único generado por la API del Operador que permite a Fast Track identificar ese mensaje SMS particular para actualizar su estado de entrega después de que sea enviado.
ERROR Respuesta JSON No-200
Las respuestas erróneas están típicamente asociadas con códigos de estado HTTP 400s o 500s. La respuesta debe contener un campo "error" con una descripción para mostrar qué salió mal y asistir con la resolución de problemas.
Las respuestas de la API del Operador serán manejadas de manera diferente dependiendo de la clase del código de estado HTTP. La tabla de abajo da un resumen de cómo los estados HTTP son manejados por separado.
| Códigos de Estado HTTP | Descripción |
|---|---|
200-299 | Exitosamente Entregado. Fast Track reconocerá el mensaje y comenzará a procesar el siguiente mensaje en la cola. |
400-499 | No Exitoso. Al recibir este error, Fast Track omitirá el mensaje SMS. Adicionalmente, enviará sus datos a Acciones Fallidas, si el servicio está habilitado. |
500 o cualquier otro código de estado que no esté listado arriba | No Exitoso. El servicio falla y Fast Track mantendrá reintentando hasta que una respuesta 200 sea recibida. |
SMS por Lotes
Los SMS por lotes ayudan a procesar una colección de SMS en una solicitud a la API. El número de mensajes dentro de la solicitud por lotes está limitado por una cantidad entera establecida en la configuración y enviada dentro de un lapso de tiempo configurado, incluso cuando el lote aún no está lleno.
Implementación del Endpoint
Implementa el endpoint en el formato de abajo para soportar SMS de envío por lotes a través de la API.
⬆️ POST <operator-api-endpoint-url>/channels/sms/batch
Header de Solicitud
El header de la solicitud enviada contiene un "X-Api-Key" que es un token requerido para autenticar las llamadas de API en el endpoint. Este token necesita ser pasado a Fast Track para hacer estas solicitudes.
Esquema del Cuerpo de Solicitud
Aquí hay un ejemplo del formato esperado cuando se agrupan las solicitudes. Es similar a la solicitud de SMS Individual pero las solicitudes están almacenadas en un array, una después de la otra.
Ver la tabla de arriba (para SMS Individual) para más detalles sobre formato, descripciones y campos requeridos.
Respuestas Esperadas
Las siguientes respuestas deben ser retornadas por la API del Operador.
Exitosa Respuesta JSON HTTP 200
El "activity.id" inicialmente enviado en la solicitud será retornado de vuelta en la respuesta como "id". Esto es requerido para ayudar a Fast Track a identificar el mensaje SMS individual en la solicitud por lotes inicial.
El "sms_id" será un identificador único generado por la API del Operador, que Fast Track usará para identificar el mensaje SMS relacionado al actualizar su estado.
Si cualquiera de las categorías listadas ("successful", "failed" o "fatal") no tienen un SMS asociado, deben ser retornadas como un array vacío.
La solicitud necesita incluir una de las propiedades successful, failed o fatal
El flujo lógico de cómo la respuesta será manejada es muy similar a cómo los códigos de estado HTTP son manejados en el SMS Individual. La única diferencia es que la respuesta con un código de estado 200 será manejada en su lugar, según la categoría del mensaje en la respuesta.
| Categoría de Respuesta | Descripción |
|---|---|
successful | Exitosamente Entregado. Fast Track reconocerá el mensaje y comenzará a procesar el siguiente lote en la cola. |
failed | No Exitoso. Al recibir este error, Fast Track omitirá el mensaje SMS. Adicionalmente, enviará sus datos a Acciones Fallidas, si el servicio está habilitado. |
fatal | Los mensajes serán reintentados |
Cualquier otro mensaje que no esté listado dentro de la respuesta será reintentado.
ERROR (respuesta no 500) Respuesta JSON
Fast Track solo soportará Código de Estado HTTP 200 en el procesamiento por lotes. Toda la solicitud por lotes será reintentada