Twilio

Capability: Notifications

Market: US, UK, CEE

SMS and email notifications. Includes Verify Service (multi-channel OTP).

Environments

UAT: https://dci-uat.ondisplayftos.com

PROD: https://dci.fintechos.com

Exposed Endpoints

SendMessage

https://<env>/dcs/message1/sendMessage

Can send a list of emails.

Copy 
[{
    "FromAddress":"cityhall@domain.com", //Sender address
    "ToAddress":"memememe@fintechos.com", //Receiver addess
    "Subject":"salut", //Subject of the e-mail
    "Body":"helloo", //Body of the e-mail
    "CorrelationId":"0aa0aa0a-0000-000a-0a0a-0aaaa0aaaa00" //Id from FintechOS, not mandatory
}]
 
Copy
{
    "EmailStatuses": [
        {
            "CorrelationId": "0aa0aa0a-0000-000a-0a0a-0aaaa0aaaa00", //ID sent in the initial request
            "StatusCode": 200, //Status of the e-mail sending as received from SendGrid
            "ErrorMsg": null, //Error field populated with error string, in case of error
            "ExternalId": "<000000000000.00000000000@smtp-relay.mailin.fr>" //Unique id given by SendGrid
        }
    ],
    "IsSuccess": true,
    "ErrorMessage": null
}

 

SendMarketingMessage

https://<env>/dcs/message1/sendMarketingMessage

This endpoint should be used by customers who send mass marketing emails, to be compliant with ‘One-Click List-Unsubscribe Header – RFC 8058’ and is the same as Send Message (same request and same response) but handles specific email headers needed for compliance. Sending mass marketing emails using the standard SendMessage endpoint can result in emails being flagged as spam, blocked by the majority of inbox providers, degraded reputation for the sendgrid account and ultimately blacklisted (unable to send any more emails)

SendSms

https://<env>/dcs/message1/sendSms

Copy
{
  "Body": "string",
  "ToAddress": "string",
  "FromAddress": "string",
  "CorrelationId": "string"
}
 
Copy
{
  "IsSuccess": true,
  "ErrorMessage": "string",
  "ExternalErrorMessage": "string",
  "ExternalErrorCode": "string",
  "CorrelationId": "string",
  "Status": 2,
  "ExternalId": "string",
  "ProviderStatusCode": "string",
  "ProviderErrorDetail": "string",
  "FragmentMessages": [
    {
      "CorrelationId": "string",
      "ProviderStatusCode": "string",
      "ProviderErrorDetail": "string",
      "ExternalId": "string",
      "Status": 2
    }
  ]
}

 

SendOcbSms

https://<env>/dcs/message1/sendOCBSms

Request and response are the same as SendMessage.

Copy
[{
    "FromAddress":"cityhall@domain.com", //Sender address
    "ToAddress":"memememe@fintechos.com", //Receiver addess
    "Subject":"salut", //Subject of the e-mail
    "Body":"helloo", //Body of the e-mail
    "CorrelationId":"0aa0aa0a-0000-000a-0a0a-0aaaa0aaaa00" //Id from FintechOS, not mandatory
}]
 
Copy
{
    "EmailStatuses": [
        {
            "CorrelationId": "0aa0aa0a-0000-000a-0a0a-0aaaa0aaaa00", //ID sent in the initial request
            "StatusCode": 200, //Status of the e-mail sending as received from SendGrid
            "ErrorMsg": null, //Error field populated with error string, in case of error
            "ExternalId": "<000000000000.00000000000@smtp-relay.mailin.fr>" //Unique id given by SendGrid
        }
    ],
    "IsSuccess": true,
    "ErrorMessage": null
}

 

CreateVerification

https://<env>/dcs/message1/createVerification

Copy
{
  "To": "string",
  "Channel": "sms", //sms, email, whatsapp
  "CustomFriendlyName": "string",
  "CustomMessage": "string",
  "Locale": "string",
  "CustomCode": "string",
  "ChannelConfiguration": "string",
  "Tags": "string"
}
 
Copy
{
  "IsSuccess": true,
  "ErrorMessage": "string",
  "ExternalErrorMessage": "string",
  "ExternalErrorCode": "string",
  "Sid": "string",
  "ServiceSid": "string",
  "AccountSid": "string",
  "To": "string",
  "Channel": 0,
  "Status": "string",
  "Amount": "string",
  "Payee": "string",
  "SendCodeAttempts": [
    {
      "Time": "2026-08-18T14:50:10.971Z",
      "Channel": 0,
      "AttemptSid": "string"
    }
  ],
  "DateCreated": "2026-08-18T14:50:10.971Z",
  "DateUpdated": "2026-08-18T14:50:10.971Z",
  "Sna": "string",
  "Url": "string"
}

 

VerifyCode

https://<env>/dcs/message1/verifyCode

Copy
{
  "Code": "string",
  "VerificationSid": "string",
}
 
Copy
{
  "IsSuccess": true,
  "ErrorMessage": "string",
  "ExternalErrorMessage": "string",
  "ExternalErrorCode": "string",
  "Sid": "string",
  "ServiceSid": "string",
  "AccountSid": "string",
  "To": "string",
  "Channel": 0,
  "Status": "string",
  "Amount": "string",
  "Payee": "string",
  "DateCreated": "2026-08-18T14:51:38.985Z",
  "DateUpdated": "2026-08-18T14:51:38.985Z",
  "SnaAttemptsErrorCodes": "string"
}

 

CreateVerificationStandard

https://<env>/dcs/message1/CreateVerificationStandard

Copy
{
  "Channel": "sms", //sms, email, whatsapp
  "To": "string",
  "Brand": "string",
  "Locale": "string",
  "ChannelTimeout": 0,
  "CustomCode": "string"
}
 
Copy
{
  "IsSuccess": true,
  "ErrorMessage": "string",
  "ExternalErrorMessage": "string",
  "ExternalErrorCode": "string",
  "SessionId": "string"
}

 

VerifyCodeStandard

https://<env>/dcs/message1/VerifyCodeStandard

Copy
{
  "SessionId": "string",
  "Code": "string"
}
 
Copy
{
  "IsSuccess": true,
  "ErrorMessage": "string",
  "ExternalErrorMessage": "string",
  "ExternalErrorCode": "string",
  "SessionId": "string",
  "Status": "string"
}
 

SendGrid (emails)

SendGrid is a division that facilitates the sending and tracking of emails. There are multiple use cases through which SendGrid can be hooked up to the platform. For the emails to be sent out properly by the provider (Twilio SendGrid), the FintechOS support rep handling your access ticket will require you to authenticate your domain with SendGrid, so that the emails sent out are verified (3 CNAME records must be added in your DNS provider for DKIM and SPF verification).

Sending Transactional Emails

Follow the steps below to send transactional emails using the connector, with delivery receipts and tracking via MessageQueue:

  1. Submit a ticket to Support, requesting access to Twilio SendGrid with webhooks.

  2. In Studio, go to Menu > Admin > Omnichannel Communication Automation > Channel Providers.

  3. Select FTOSEmailGateway:

  4. Fill in:

    • SendMessage endpoint -> Service Url field

    • Subscription Key received in the Service Access Ticket => App Key field

    • Your from address in the From field (default sending address)

Add your message in the message queue with the configured channel provider by using the email server SDK functions described here Server SDK Reference Guide and specify the channel provider parameter as “FTOSEmailGateway”.

You can work with a secondary / backup provider or even a custom channel configuration (create your own channel provider with the settings you need). However, when doing so, you will also need to add the handling of this channel provider in the JobServer PlatformServices Vault Settings → Services config and Triggers config (FTOSEmailGateway is already configured and is handled by the JobServer out-of-the-box)

The entity FTOS_DPA_MessageQueue is where the messages are stored (to be sent by the JobServer). By using SendMessage, the delivery receipts and tracking events will arrive back at the platform and will be stored in the entity FTOS_DPA_MessageEvent correlated by the FTOS_DPA_MessageQueueId column.

Sending Marketing Emails via the connector

  1. Submit a ticket to Support, requesting access to Twilio SendGrid (emails) with or without webhooks (if you want tracking or not. keep in mind, marketing emails usually means around 50000 emails in 24h, and their tracking events can generate a lot of spam inbound as 1 email usually translates to 2-5 tracking events returned to the platform. this could result in high resource consumption when the events are ingested by the platform).

  2. In Studio, go to Menu > Admin > Omnichannel Communication Automation > Channel Providers.

  3. Select FTOSEmailGateway or create your own custom marketing channel provider

  4. Fill in:

    • Twilio SendMarketingMessage → Service Url

    • Subscription Key received in the Service Access Ticket => App Key field

    • Your from address in the From field (default sending address)

    • Configure the Bulk processing for the channel provider (send 100/1000 emails at once)

  5. Add your marketing emails to the MessageQueue using your desired custom service/script and using your desired email template (ftos.messaging.send).

If you are using a custom marketing channel provider, be sure to add it to Vault JobServer-PlatformServices Services config and Triggers Config so that the JobServer can expedite them.

Sending Transactional Emails

Follow the steps below to send transactional emails using Twilio SMTP (fire-and-forget, no delivery receipts, straight to provider, skipping the connector):

  1. Create a ticket to Support, requesting access to Twilio Sendgrid using SMTP.

  2. In Studio, go to Menu > Admin > Omnichannel Communication Automation > Channel Providers. Create a new channel provider:

  3. Fill in the fields:

    • Provider Name: smtp, and give it a name (ex: SmtpEmail).

    • Service Url: add the provider smtp address and port. ex: smtp-relay.provider.com:587

    • App User: the smtp user (defined in the provider account, will be provided in the ticket response)

    • App Key: the smtp key (defined in the provider account, will be provided in the ticket response)

  4. Go to Vault settings > JobServer-PlatformServices and add the smtp channel provider to the Services config (add this json config object in the Services configuration list):

    Copy
    {
        "execParams": "provider=smtp;providerSetting=SmtpEmail",
        "Assembly": "FintechOS.Jobs.MessageDelivery.ScheduledServices",
        "Class": "FintechOS.Jobs.MessageDelivery.ScheduledServices.SendMessagesService",
        "Method": "",
        "Name": "FTOS.SendMessagesServiceSmtp",
        "SendNotification": null,
        "Type": "class"
      }

  5. Also here, modify the Triggers config to add the scheduler for handling the smtp channel provider (add this json config object in the Triggers configuration list):

    Copy
    {
        "Async": false,
        "Calendar": null,
        "EndTime": "03.11.2080 11:02",
        "Expression": "0/30 * * * * ?",
        "Name": "FTOS.SendMessagesServiceSmtp",
        "PoolTime": null,
        "RepeatCount": "-1",
        "RescheduleAfterRun": false,
        "Services": [
          "FTOS.SendMessagesServiceSmtp"
        ],
        "StartTime": "02.11.2020 11:00"
    }

  6. Restart JobServer-PlatformServices so it can load the newly configured settings.

  7. Add your message in the message queue using the configured channel provider by using the the email server sdk functions described here Server SDK Reference Guide and specify the channel provider parameter as your defined smtp channel provider (ex: SmtpEmail as seen in the above channel provider configuration screen).

Twilio SMS

Twilio also supports sending transactional SMS.

NOTE  
These SMS should be transactional and informational such as “your payment is due in x days” and not OTP/MFA/SMS Verification. For these cases see Verify Service (MFA/OTP) below.

There are two use cases supported by the connector:

  • SendSms (fire and forget, no delivery receipt, configuration is done in Vault)

  • SendOcbSms (uses MessageQueue and JobServer, can support delivery receipts, must configure a Channel Provider in Omnichannel Communications). This is useful when reminding end-users of the interest rate increasing or that a payment is due, thus ensuring and keeping evidence that the customer indeed received the notification. Can also be used for marketing SMS.

Send Transactional SMS directly from automation script

  1. Create a ticket to Support, requesting access to Twilio SMS with no webhooks.

  2. Go to Vault > Portal / B2C Portal / or your custom portal from where your script will be executed at runtime (journey) > AppSettings and add the following key and value:

    FtosApiSmsProvider

    Copy
    {
      "from":"SenderID", // do not use @ or other special characters
      "serviceUrl":"endpoint",
      "subscriptionKey":"subscription key"
    }

  3. You can register your SenderID (lease) with a Telco company so that the end-user receives sms from the senderId you define. In some countries like Ireland, this is mandatory. Otherwise, depending on the country and regulations, your senderId will be ignored and sms will be received by the end-user from a short-code number as supported by the Telco companies.

  4. ServiceUrl should be Twilio | SendSms as instructed in the support ticket.

  5. Subscription key will be the one received from the support ticket.

  6. In your automation script that will send the sms, call the ftos server sdk function sendSms as described here Server SDK Reference Guide, and specify the “provider” parameter as “FtosApiSms”.

Send Transactional or Marketing SMS using the MessageQueue (JobServer)

IMPORTANT!  
This is not suitable for using with ftos.messaging.sendSMS.

  1. Create a ticket to Support, requesting access to Twilio SMS with or without webhooks (depending on your use case).

  2. In Studio, go to Menu > Admin > Omnichannel Communication Automation > Channel Providers.

  3. Select FtosApiSms or create your own custom sms channel provider. Fill in the following:

    • Set Communication Channel to SMS

    • Set Name (if not already created)

    • Set the Service URL to Twilio | SendOcbSms according to the instructions received in the support ticket

    • Set the subscription key, provided to you via ticket

  4. Configure From. Make sure you don’t set something that has @ in it. Depending in which countries you will be sending your SMS, some carriers may block / reject / hard bounce messages that have an email address in the “From” field.

  5. Scroll down to the final section (Channel Provider Statuses) and add all Channel Provider Statuses shown in this picture (really important) & assign proper Message Status IDs to each Status:

    In Progress: 200, 202, bounce

    Sent: delivered

    Error: 400, 401, 403, 404, 405, 413, 415, 429, 500, 503, dropped

  6. Go to Vault → JobServer-PlatformServices and add the sms channel provider to the Services config (add this json config object in the Services configuration list).

    Copy
    {
        "execParams": "provider=ftosProvider;providerSetting=FTOSApiSms",
        "Assembly": "FintechOS.Jobs.MessageDelivery.ScheduledServices",
        "Class": "FintechOS.Jobs.MessageDelivery.ScheduledServices.SendMessagesService",
        "Method": "",
        "Name": "FTOS.SendMessagesServiceSMS",
        "SendNotification": null,
        "Type": "class"
      }

  7. Also here, modify the Triggers config to add the scheduler for handling the smtp channel provider (add this json config object in the Triggers configuration list).

    Copy
    {
        "Async": false,
        "Calendar": null,
        "EndTime": "03.11.2080 11:02",
        "Expression": "0/30 * * * * ?",
        "Name": "FTOS.SendMessagesServiceSmtp",
        "PoolTime": null,
        "RepeatCount": "-1",
        "RescheduleAfterRun": false,
        "Services": [
          "FTOS.SendMessagesServiceSmtp"
        ],
        "StartTime": "02.11.2020 11:00"
    }

  8. Restart JobServer-PlatformServices so it can load the newly configured settings.

  9. Add your message in the message queue with the configured channel provider by using the server sdk functions described here Server SDK Reference Guide that can insert messages to MessageQueue and specify the channel provider parameter as “FtosApiSms” or your custom defined channel provider.

Verify Service (MFA/OTP)

Twilio offers the possibility of handling MFA/OTP integrations via the Verify Service. The service has a 2-step operational flow:

  • Create a verification - sends a verification code to the end-user via the specified communication channel and the platform receives a sessionId
  • Verify Code - end-users input their code in the platform, the platform sends the code & sessionId to the Verify service in order to validate.

There are two important use cases inside the platform where MFA/OTP/Verification can be used:

  • Inside the Journey
  • At Studio/Portal user login

Verify Service inside the journey

  1. Create a ticket to Support, requesting access to Twilio Verify.

  2. Go to Vault Portal/B2C where your journeys will be run by the end-users and add the following keys:

    • FTOSServicesTwilioVerifyAppId = the subscription key received in the ticket
    • FTOSServicesTwilioVerifyEndpoint = the endpoint received in the ticket.

Install/Deploy FTOS Verify Processor

You can use the Twilio Verify Processor settings (Studio Menu/Workflows/Digital Flow Processing and open Twilio Verify Processor Settings) along with the Verify widget example provided in the installed package, or you can assemble the payload yourself inside an automation script as described in the CreateVerification section above.

Example of implementation, using processor settings and widget:

Copy
var element = document.getElementById("widgetContainer");
    var options = {
        hideTitle: false,
        skipJavascript: false,
        context: {
            ProcessorSettingsId: procSettingsId,
            Service: service,
            Debug: true        
        }
    };

    ebs.generateHtmlWidgetAsync("Verify", element, options)
        .then(function () {
            console.log("widget generated");
        })
        .catch(function (err) {
            console.log(err);
        });

 

Verify Service at Studio/Portal login via Keycloak

  1. Create a ticket to Support, requesting access to Twilio Verify.

  2. Open your Keycloak admin panel and make sure you have fintechOSrealm selected.

  3. Navigate to Authentication and open OTP Verify Services (or create your own custom auth flow).

  4. Inside the flow, edit the OTP Verify Authentication step:

    • OTP Verify Base Url: <https://<env>/dcs/message1 where the environment is Twilio | Environments, should be received in the ticket.

    • OTP Verify Auth Header Value: subscription key as received from the ticket.

    • Brand: your SenderId.

    • Channel timeout: the expiration of the OTP.

    • Allow Email/SMS/WhatsApp: allow the user to select between the various supported channels.

  5. Then go to Clients, and select the service account under which the required platform section is running (studio/portal). Go to Advanced and scroll all the way down to Authentication Flow Overrides, and select your flow for Browser Flow: