Use custom SMS providers

To authenticate users or to verify their phone numbers, you can deliver one-time passcodes (OTPs) in SMS messages.

By default, SMS messages are delivered via Mosaic's built-in SMS service. This service is intended for low-volume evaluation and testing purposes only, and is not designed for high-volume production use. For production environments, configure the platform to send SMS messages via Twilio, Salesforce Marketing Cloud (SMC), or other backend integrations. The configuration is set on a tenant level.

Using a third-party SMS provider is recommended when you need reliable delivery at scale, custom sender phone numbers (e.g., local numbers that are often considered more credible), or access to the provider's delivery logs for troubleshooting.

Go to Settings > SMS provider.

If you choose Default under SMS Provider, the platform will dispatch all your SMS messages via Mosaic's own SMS service. This option doesn't require additional configuration outside Mosaic's APIs.

You can set up Twilio as your SMS provider from the Admin Portal.

From Settings > SMS provider, select Twilio as the SMS provider and configure the following settings:

• Account SID: your Twilio account SID
• Auth Token: your Twilio auth token
• Sender setting: Allows you to either configure the sender phone number directly, or the Messaging Service ID to use the sender settings configured for your Twilio Messaging Service

You can set up Salesforce Marketing Cloud (SMC) as your SMS provider from the Admin Portal.

From Settings > SMS provider, select Salesforce Marketing Cloud as the SMS provider and configure the parameters:

• Subdomain: Your Salesforce subdomain.
• Client ID: Your client identifier with Salesforce (also known as Consumer key).
• Client Secret: Your client secret with Salesforce (also known as Consumer secret).
• Message ID: The identifier of the message definition (template) configured in MobileConnect. It points to a pre-configured SMS template in Salesforce Marketing Cloud so that every send request uses the correct message format. For example, if you created a definition with "definitionKey": "otp-verification", use otp-verification as the Message ID.
• Package Type: Determines which Salesforce Marketing Cloud installed package type is used for authentication. Default value: enhanced. Enhanced packages use OAuth 2.0 and are the standard for all Marketing Cloud accounts created after August 2019. Select legacy only if your Marketing Cloud account still uses a legacy installed package (created before January 2019). Note that Salesforce has ended support for legacy packages.

Visit Salesforce: Safety Cloud for further information.

You can integrate with other custom SMS providers by implementing a gateway. This gateway should listen for messages from Mosaic whenever you need to send an SMS. Once the gateway receives a message, it should forward it as an SMS through the provider you've set up on your end.

For a custom SMS gateway, you need to implement the following:

• Two endpoints:
  • POST endpoint for SMS processing
  • GET endpoint for endpoint validation
• One API call: register the endpoints with Mosaic

To implement the SMS gateway:

1. Create an endpoint for SMS processing. Upon an incoming POST request with SMS data, the endpoint should check the X-API-Key value (must match api_key in step 3), dispatch the SMS, and respond with a success code (200). Example incoming cURL request:

# Example endpoint URI: "https://acme.com/send-sms"
curl --location --request POST '[GATEWAY_ENDPOINT_URI]' \
--header 'Content-Type: application/json' \
# API Key for endpoint registration (see step 3)
--header 'X-API-Key: {API_KEY}' \
--data '{
    "phone_number": string,
    "sender_id": string,
    "message": string
}'

2. Create an additional GET endpoint (at the same URL) that handles the validation challenge. This endpoint should be able to accept a GET request with a payload like this:

Accept: application/json, text/plain, */* \
content-length: 0 \
Host: example.com \
# API Key for endpoint registration (see step 3)
X-API-Key: abcd1234-0fae-4ce6-97c4-ca9ad4123b0d \
X-Scheme: https \
X-Verification-Key: AbCdZ3hJxx826qTmvwepy \

Each validation request includes a random X-Verification-Key value in the header. The verification endpoint should extract this value and echo it back in the response body so Mosaic can match the request and response. Here's an example implementation that can process the validation challenge:

app.define('/send-sms','GET', function(req, res) {

    // Retrieve the header value.
    var key = req.get("X-Verification-Key");
    // API key you register in step 3.
    var my_api_key = "abcd1234-0fae-4ce6-97c4-ca9ad4123b0d";

    // Make sure that the API key in the request is the same you specify in step 3.
    if (req.get("X-API-Key") != my_api_key) {  return res.send(400, "Invalid request"); }

    // Set the response type.
    res.type('application/json');

    // Set the status code of the response.
    res.status(200);

    // Send the key value in the response body.
    res.json({  "key": key  });
}

3. Register your endpoints on the platform. To do that, send a one-time request like this:

curl --location --request PUT 'https://api.transmitsecurity.io/cis/v1/tenantsmsproviders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer{BEARER_TOKEN}' \
# Include the gateway details in the payload.
# Example URI: "https://acme.com/send-sms"
--data '{
    "provider": "CustomGateway",
    "custom_gateway":{
        "uri": "{GATEWAY_ENDPOINT_URI}",
        "api_key": "{API_KEY}"
}'

Upon this request, Mosaic updates your SMS provider configuration and responds with the validation challenge (see step 2). If the validation is successful, the platform will start delivering SMS messages to your POST endpoint (see step 1).