twillio_verify

A Gleam library for sending and verifying SMS codes using the Twilio Verify API.

Installation

Add twillio_verify to your gleam.toml dependencies:

[dependencies]
twillio_verify = { path = "../twillio_verify" }

Configuration

Create a TwilioConfig with your Twilio credentials:

import twillio_verify.{TwilioConfig}

let config = TwilioConfig(
  account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  auth_token: "your_auth_token",
  service_sid: "VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

You can find these values in your Twilio Console:

Account SID and Auth Token: Found on the main dashboard
Service SID: Create a Verify Service under Verify > Services

Usage

Sending a Verification Code

import gleam/httpc
import twillio_verify.{TwilioConfig, Sms}

let config = TwilioConfig(
  account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  auth_token: "your_auth_token",
  service_sid: "VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

// Build the request
let request = twillio_verify.send_verification_request(config, "+1234567890", Sms)

// Send with your HTTP client
let assert Ok(response) = httpc.send(request)

// Parse the response
case twillio_verify.send_verification_response(response) {
  Ok(verification) -> {
    io.println("Verification sent! SID: " <> verification.sid)
    io.println("Status: " <> string.inspect(verification.status))
  }
  Error(error) -> {
    io.println("Error: " <> string.inspect(error))
  }
}

Checking a Verification Code

import gleam/httpc
import twillio_verify.{TwilioConfig}

let config = TwilioConfig(
  account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  auth_token: "your_auth_token",
  service_sid: "VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

// Build the request
let request = twillio_verify.check_verification_request(config, "+1234567890", "123456")

// Send with your HTTP client
let assert Ok(response) = httpc.send(request)

// Parse the response
case twillio_verify.check_verification_response(response) {
  Ok(verification) -> {
    case twillio_verify.is_approved(verification) {
      True -> io.println("Code verified successfully!")
      False -> io.println("Invalid code")
    }
  }
  Error(error) -> {
    io.println("Error: " <> string.inspect(error))
  }
}

Available Channels

import twillio_verify.{Sms, Call, Email, Whatsapp}

// Send via SMS
twillio_verify.send_verification_request(config, "+1234567890", Sms)

// Send via phone call
twillio_verify.send_verification_request(config, "+1234567890", Call)

// Send via email
twillio_verify.send_verification_request(config, "user@example.com", Email)

// Send via WhatsApp
twillio_verify.send_verification_request(config, "+1234567890", Whatsapp)

Response Types

SendVerificationResponse / CheckVerificationResponse

Both response types include:

Field	Type	Description
`sid`	`String`	Unique identifier for this verification
`account_sid`	`String`	Your Twilio Account SID
`service_sid`	`String`	The Verify Service SID
`to`	`String`	The phone number or email
`channel`	`String`	Channel used (sms, call, email, whatsapp)
`status`	`VerificationStatus`	Current status (Pending, Approved, Canceled)
`valid`	`Bool`	Whether the verification is valid
`amount`	`Option(String)`	Amount for PSD2 verifications
`payee`	`Option(String)`	Payee for PSD2 verifications
`date_created`	`String`	ISO 8601 creation timestamp
`date_updated`	`String`	ISO 8601 update timestamp
`lookup`	`Lookup`	Carrier lookup information
`send_code_attempts`	`List(SendCodeAttempt)`	List of send attempts
`url`	`String`	API URL for this verification

Error Handling

The library returns TwilioError for failures:

case twillio_verify.send_verification_response(response) {
  Ok(verification) -> // handle success
  Error(twillio_verify.TwilioApiError(code, message, more_info)) -> {
    // Twilio API error (e.g., invalid phone number)
    io.println("Twilio error " <> int.to_string(code) <> ": " <> message)
  }
  Error(twillio_verify.UnexpectedResponseError(status, body)) -> {
    // Unexpected HTTP response
    io.println("HTTP " <> int.to_string(status) <> ": " <> body)
  }
  Error(twillio_verify.DecodeError(reason)) -> {
    // JSON decode failure
    io.println("Decode error: " <> reason)
  }
}

License

MIT