Custom SMS Solution

Integrating a custom SMS solution/provider as part of your Operator API

Fast Tracks supports a variety of SMS providers, if your business need a provider which is not a part of the list of supported providers then you can build this API.

Fast Track SMS Service

The Fast Track SMS service can be configured to send SMS requests to the Operator API endpoints listed below, which allows the Operator to manage the SMS provider. It supports sending messages and to get fetch delivery status. Sending is available for both single or batched SMS requests.

The following endpoints can be built as a part for your Operator API:

⬆️ POST /channels/sms/single

⬆️ POST /channels/sms/batch

The Operator can then forward these requests to the SMS provider for processing and answer back with the respective responses.

API format and responses need to be formatted as outlined below

It is important that the "meta" data outlined below is sent back to Fast Track in either Webhook or Polling so that conversion data can be stored correctly. Please refer to the shown examples and the tables underneath for further clarification.

Pre-Requisites

Advice Fast Track if any rate limiting should be taken into consideration. (If you plan to implement rate limiting please contact Fast Track before, so we can guide you on supported implementation)
Advice Fast Track if any batch maximums should be taken into consideration.
Provide Fast Track with any credentials specific for the integrated providers (if required)
Supported SMS formats are GSM7 & USC2

Send SMS (Single)

A single SMS send request will contain the data of each individual SMS in separate requests to the API.

Endpoint Implementation

Implement the endpoint in the format below to support single-send SMS through API.

⬆️ POST <operator-api-endpoint-url>/channels/sms/single

Request Header

The header of the sent request contains an "X-Api-Key" which is a token required to authenticate the API calls at the endpoint. This token needs to be passed on to Fast Track in order to make these requests.

Request Body Schema

Refer to the following example of a single SMS request sent by Fast Track. The description of each field is listed in the table below it.

{
  "activity": {
    "id": "12312-12312-123123-123123",
    "brand_id": 1,
    "user_id": "1123111",
    "internal_user_id": 1123112,
    "activity_id": 123,
    "action_group_id": 443,
    "trigger_hash": "asd777dsDSD778sd80-asdas",
    "action_id": 1224
  },
  "content": "TEST Deposit Free Bet 22 - 13th April",
  "recipient": "254716595289",
  "sender_name": "Casino1",
  "provider_name": "LinkMobility",
  "encoding": "auto"
}

Key

Type

Desctiption

activity.id

integer

A unique identifier of the SMS

activity.brand_id

integer

The unique identifier of the brand on Fast Track

activity.user_id

string

The unique identifier of the player

activity.activity_id

integer

The unique identifier of the activity setup in Fast Track

activity.action_group_id

integer

The unique identifier of the action group which the SMS originates from Fast Track

activity.trigger_hash

string

Trigger hash

activity.action_id

integer

The unique identifier of the individual action from Fast Track

content

string

The content of the SMS

recipient

string

The recipient number

sender_name

string

The sender name of the SMS

provider_name

string

The name of the integrated provider

encoding

string

Type of encoding of SMS. Can be "auto", "gsm7" or "usc2"

Expected Responses

The Operator API should return the responses for each individual SMS message respectively to avoid unrelated storage of SMS data.

Successful HTTP 200-299 JSON Response

The "sms_id" will be a unique identifier generated by the Operator API which allows Fast Track to identify that particular SMS message in order to update its delivery status after it is sent.

{
  "sms_id": "123123"
}

ERROR Non-200 response JSON Response

Erroneous responses are typically associated with HTTP status codes 400s or 500s. The response should contain an "error" field with a description to show what went wrong and assist with troubleshooting.

{
    "error": "a description of the error"
}

The responses from the Operator API will be handled differently depending on the class of the HTTP status code. The table below gives a summary of how the HTTP status are handled separately.

HTTP Status Codes

Description

200-299

Successfully Delivered. Fast Track will acknowledge the message and start processing the next message in the queue.

400-499

Non Successful. When receiving this error, Fast Track will skip the SMS message. Additionally, it will send its data to Failed Actions, if the service is enabled.

500 or any other status code which is not listed above

Non Successful. The service fatals and Fast Track will keep retrying until a 200 response is received.

Batch SMS

Batch SMS helps to process a collection of SMS in one request to the API. The number of messages within the batch request is limited by a set integer amount in the configuration and sent within a configured time span, even when the batch is not yet full.

Endpoint Implementation

Implement the endpoint in the format below to support batch-send SMS through API.

⬆️ POST <operator-api-endpoint-url>/channels/sms/batch

Request Header

Request Body Schema

Here is an example of expected format when batching the requests. It is similar to the Single SMS request but the requests are stored in an array, one after the other.

[
  {
    "activity": {
      "id": "12312-12312-123123-123123"
      "brand_id": "Brand1",
      "user_id": "1123112",
      "internal_user_id": "1123112",
      "activity_id": "123",
      "action_group_id": "443",
      "trigger_hash": "asd777dsDSD778sd80-asdas",
      "action_id": "1224"
    },
    "content": "TEST Deposit Free Bet 22 - 13th April",
    "recipient": "254716595289",
    "sender_name": "Casino1",
    "provider_name": "LinkMobility"
    "encoding": "auto" // gsm7 / usc2
  },
  {
    "activity": {
      "id": "12312-12312-123123-123123"
      "brand_id": "Brand1",
      "user_id": "1123112",
      "internal_user_id": "1123112",
      "activity_id": "123",
      "action_group_id": "443",
      "trigger_hash": "asd777dsDSD778sd80-asdas",
      "action_id": "1224"
    },
    "content": "TEST Deposit Free Bet 22 - 13th April",
    "recipient": "254716595289",
    "sender_name": "Casino1",
    "provider_name": "LinkMobility"
    "encoding": "auto" // gsm7 / usc2
  }
]

Key

Type

Description

activity.id

integer

A unique identifier of the SMS

activity.brand_id

integer

The unique identifier of the brand on Fast Track

activity.user_id

string

The unique identifier of the player

activity.activity_id

integer

The unique identifier of the activity setup in Fast Track

activity.action_group_id

integer

The unique identifier of the action group which the SMS originates from Fast Track

activity.trigger_hash

string

Trigger hash

activity.action_id

integer

The unique identifier of the individual action from Fast Track

content

string

The content of the SMS

recipient

string

The recipient number

sender_name

string

The sender name of the SMS

provider_name

string

The name of the integrated provider

encoding

string

Type of encoding of SMS. Can be "auto", "gsm7" or "usc2"

Expected Responses

The below responses should be returned by the Operator API.

Successful HTTP 200 JSON Response

The "activity.id" initially sent in the request will be returned back in the response as "id". This is required to help Fast Track identify the individual SMS message in the initial batch request. The "sms_id" will be a unique identifier generated by the Operator API, which Fast Track will use to identify the related SMS message when updating its status. If any of the listed categories ("successful", "failed" or "fatal") do not have an associated SMS, they should be returned as an empty array.

The request need to include one of the properties successful, failed or fatal

{
    "successful": [
        {
            "id": "{activity.id(from request)}",
            "sms_id": "123123"
        },
        {
            "id": "{activity.id(from request)}",
            "sms_id": "123123"
        }
    ],
    "failed": [
        {
            "id": "{activity.id(from request)}",
            "sms_id": "unique-id-of-the-sms (if applicable)",
            "error": "why it failed"
        }
    ],
    "fatal": [
        {
            "id": "{activity.id(from request)}",
            "sms_id": "unique-id-of-the-sms (if applicable)",
            "error": "why it failed"
        }
    ]
}

The logic flow on how the response will be handled is very similar to how the HTTP status codes are handled in the Single SMS. The sole difference is that the response with a status code 200 will be handled instead, according to the message's category in the response.

Response Category

Description

successful

Successfully Delivered. Fast Track will acknowledge the message and start processing the next batch in the queue.

failed

Non Successful. When receiving this error, Fast Track will skip the SMS message. Additionally, it will send its data to Failed Actions, if the service is enabled.

fatal

Messages will be retried

Any other messages that are not listed within the response will be retried.

ERROR (non 500 response) JSON Response

Fast Track will only support HTTP Status Code 200 in batching. The whole batch request will be retried if any other status code is received with the following response.

{
    "error": "the error"
}

Conversion Data

We support retrieving conversion data through webhook.

Webhook

Fast Track will provide a Webhook URL & X-API-KEY that you can send the conversion data for each SMS.

The X-API-KEY supplied is expected as a header in the request.

It's important that the "activity" data which is provided from Fast Track in the Send SMS request is sent back

POST {supplied-url}/sms/conversion

[
    {
        "activity": {
            "id": "12312-12312-123123-123123",
            "brand_id": 1,
            "user_id": "1123112",
            "internal_user_id": 1123112,
            "activity_id": 123,
            "action_group_id": 443,
            "trigger_hash": "asd777dsDSD778sd80-asdas",
            "action_id": 1224
        },
        "sms_id": "1234",
        "delivery_status": "delivered" // Refer to table below for the list of statuses
    }
]

Key

Type

Description

activity.id

integer

A unique identifier of the SMS

activity.brand_id

integer

A unique identifier of the brand on Fast Track

activity.user_id

integer

Identifier of the player

activity.activity_id

integer

Identifier of the activity setup in Fast Track

activity.action_group_id

integer

Identifier of the action group which the SMS originates from in Fast Track

activity.trigger_hash

string

Trigger hash

activity.action_id

integer

The unique identifier of the individual action from Fast Track

sms_id

string

The unique identifier of the SMS

delivery_status

string

Delivery status of the SMS

Status (delivery_status)

Description

delivered

Message delivered successfullay to the ultimate receiver

undelivered

Message undelivered to the ultimate receiver

failed

Message failed to be sent to the ultimate receiver

delivery_unknown

Message delivery is unknown. Any status which is not in the list will also be marked with unknown status.

PreviousAuthentication Endpoint NextCustom Email Solution

Last updated 1 year ago

Was this helpful?