How is your experience with the OutSystems Community?
twilio-verify-connector
Service icon

Twilio Verify Connector

Stable version 1.0.1 (Compatible with OutSystems 11)
Uploaded
 on 18 Nov (15 hours ago)
 by 
0.0
 (0 ratings)
twilio-verify-connector

Twilio Verify Connector

Documentation
1.0.1

Overview

Twilio generates, delivers, and checks the code, so your app never stores or compares codes. The connector is a Service module (TwilioVerifyConnector) that calls the REST API directly, with no extension or SDK.

Typical flow:

  1. CheckConfiguration() confirms once that the credentials and the Verify Service are correct. It sends nothing.
  2. SendAuth(To, Channel) sends the code by SMS, voice call, e-mail, WhatsApp or Silent Network Auth and returns the verification SID.
  3. The user types the code; Verify(sid, Code) returns Success = True and Status = "approved" when it is correct.
  4. Optional: GetVerification(SID) reads the state without using a check attempt; CancelVerification(SID) cancels a pending verification.

Every action returns Success, ErrorCode, and ErrorMessage and never throws.

Requirements and setup

The connector works once three site properties are set in each environment.

Requirements

  • OutSystems 11; Reactive Web, Mobile, or Traditional Web consumers.
  • A Twilio account and a Verify Service (Twilio Console > Verify > Services > Create).
  • Optional channels enabled in the Verify Service: e-mail needs a SendGrid integration, WhatsApp a WhatsApp sender, and SNA needs Twilio approval.
  • The BinaryData extension is installed in the environment.


Setup

  1. Install the component from the Forge (TwilioVerifyConnector + TwilioVerifyDemo).
  2. In Service Center > Factory > Modules > TwilioVerifyConnector > Site Properties
    1. TwilioAccountSID: Account SID (AC…), from the Twilio Console
    2. TwilioAuthToken: Auth Token, from the Twilio Console
    3. VerifyServiceId: Verify Service SID (VA…)
  3. In the consumer module, open Manage Dependencies > TwilioVerifyConnector and select the actions you use.
  4. Call CheckConfiguration(), for example, from an admin screen. Success = True and the Verify Service name to confirm the setup.

Never put credentials in literals, defaults, or code: only in the site properties.

Action reference

Five public server actions. Each takes an optional ServiceSid that overrides the VerifyServiceId site property for one call.

SendAuth sends a code.

  • Inputs: To, Channel = "sms", Locale = "en", CustomFriendlyName, CustomCode, ServiceSid, TemplateSid, AppHash, Tags, RateLimits, RiskCheck.
  • Outputs: SID, Success, Status, ErrorCode, ErrorMessage.


Verify checks the code the user typed.

  • Inputs: sid, Code, To, ServiceSid.
  • Outputs: Success, Status, ErrorCode, ErrorMessage.


CancelVerification cancels a pending verification.

  • Inputs: SID, ServiceSid.
  • Outputs: Success, Status, ErrorCode, ErrorMessage.


GetVerification reads the state without using a check attempt.

  • Inputs: SID, ServiceSid.
  • Outputs: Success, Status, Channel, To, CreatedOn, ErrorCode, ErrorMessage.


CheckConfiguration tests the credentials and the Verify Service without sending anything.

  • Inputs: ServiceSid.
  • Outputs: Success, ServiceName, CodeLength, ErrorCode, ErrorMessage.

SendAuth inputs

  • To (mandatory): an E.164 number (+country code and number) for sms, call, WhatsApp, and SNA; an email address for email.
  • Channel: sms (default), call, email, WhatsApp, or sna.
  • Locale: default en. Leave it empty to let Twilio pick the language from the destination (supported languages).
  • CustomFriendlyName: the name shown in the message.
  • CustomCode: your own code; Twilio must enable this for your account. Hidden in logs.
  • TemplateSid: a message template (HJ…) approved in the Twilio Console.
  • AppHash: the Android SMS Retriever hash, so the app reads the code automatically.
  • Tags: JSON with up to 10 key/value pairs, e.g. {"userId":"123"}. No personal data.
  • RateLimits: JSON with values for your Programmable Rate Limits, e.g. {"user_id":"123"}.
  • RiskCheck: enable or disable Fraud Guard for this call; empty uses the service setting.


Error codes

ErrorCode = 0 means success; negative codes come from the connector and positive codes from Twilio. ErrorMessage holds a readable message for the common cases and Twilio's own message for the rest.

  • 0: success. For Verify, also a wrong code, with Status = pending: check Success and Status.
  • -1: Twilio could not be reached (timeout or network error). The error is logged; try again later.
  • -2: Site properties not configured. Set them in Service Center.
  • 60200: Invalid parameter; checked locally or by Twilio. Fix the destination or the channel.
  • 60202: too many check attempts (5). Send a new code.
  • 60203: too many send attempts for this destination. Wait 10 minutes.
  • 20404: verification not found: expired (10 min), already approved or canceled. Send a new code.
  • 20003: authentication failed. Check TwilioAccountSID and TwilioAuthToken.
  • 20429 / 60212: too many requests. Slow down.
  • 60223: channel not enabled in the Verify Service. Enable it in the Twilio Console.
  • 60410: blocked by Twilio fraud protection. Review Fraud Guard and Geo Permissions.
  • Other: any other Twilio error. See ErrorMessage and the Twilio error reference.


Known limitations

  • No webhooks or status callbacks; read the state with GetVerification.
  • No automatic retry or back-off; a network failure returns -1 at once.
  • OutSystems 11 only; not built for ODC.
  • Still to confirm at runtime: Twilio error bodies with a numeric status field must map into the Text Status attribute; if not, those errors return -1 instead of the Twilio code.

1.0.0

Twilio Account Creation Tutorial 

Account

  1. Access Twilio: Twilio | Try Twilio Free
  2. Fill in the sign-up details and verify the registration email to validate the account.
  3. Verify your account and add a phone number for 2FA verification.
  4. Fill out the initial setup questionnaire, making it important to select "Identity & Verification (OTP & 2FA)" in the first option and "Verify" in the second option.
  5. After completing the questionnaire, you will be redirected to the Twilio Console.

API Keys and Token

  1. You would navigate to the Account section and locate the API keys & tokens option.
  2. Click on the "Create API Key" button.
  3. After creating the key, save the indicated data for later configuration. In this step, you will have the SID and Secret Key.
  4. "Get the Account SID for Setup. Goto option Account > Manage account -> General Settings and get the value of the field Account SID.

Configure the Twilio Verify

Twilio Verify offers a "Try it out" feature for users interested in exploring their services. Click on the "Start Building" to begin creating the first Twilio Verify Service.


To finalize the setup process, carefully go through the wizard to ensure all settings are correct. Select the plan that best fits your needs. Once you've made your choice, conclude the setup by clicking the "Save and Close" button.

Navigating a product page efficiently can enhance the user experience significantly. By selecting the "services" menu entry, users can access a comprehensive view of all the services they have created and configured.


Configure the connector

To configure the TwilioVerifyConnector module in the Service Center, navigate to the Site Properties tab. Here, you'll need to enter the AccountSID, AuthToken, and ServiceId that you've previously acquired. This will ensure the module is properly set up with your Twilio account details.



Demo

Launch the demo application, input the designated phone number to receive a verification code, and then enter the code upon receipt to confirm the outcome