SMS setup

This guide walks through enabling SMS for your Wocha tenant — from provider credentials to test delivery. SMS powers phone verification, SMS MFA enrolment, and consent-time step-up challenges.

Prerequisites

• A Wocha tenant with Console access
• An account with one or more SMS providers (Twilio, Vonage, MessageBird, or AWS SNS)
• A verified sender number or originator approved by your provider

Step 1 — Enable SMS

1. Open the Console and navigate to Settings → SMS
2. Toggle SMS enabled to on
3. Select your primary provider from the dropdown

Each provider requires different credentials:

Enter the credentials for your chosen provider and save.

Step 2 — Configure failover (optional)

Wocha automatically retries with a fallback provider when the primary fails with a retryable error (timeout, 5xx, rate limit).

1. Under Failover provider, select a secondary provider
2. Enter credentials for the fallback provider
3. Save

Failover events are logged to the audit trail. The delivery dashboard shows per-provider success rates so you can monitor failover frequency.

Step 3 — Enable SMS MFA

If you plan to use SMS as an MFA factor:

1. Toggle SMS MFA enabled to on
2. Add sms to your MFA policy allowed factors under Settings → Security → MFA Policy
3. Optionally set Preferred factor to SMS for users enrolled with multiple factors

SMS MFA requires users to verify a phone number before enrolment. See the Phone API reference for the verification flow.

Step 4 — Customise SMS templates

Navigate to Branding → Templates and select the SMS channel. Four template keys are available:

Template variables

Character limits

SMS messages are limited to 160 characters for a single segment. Messages exceeding 160 characters are split into multiple segments (up to 320 characters for two segments). The template editor shows a character counter with segment warnings.

Step 5 — Tune rate limits

Under Settings → SMS, configure:

These limits protect against SMS pumping (toll fraud) and runaway costs. The gateway also enforces a global circuit breaker that pauses delivery when a provider's error rate exceeds 50% over a 5-minute window.

Adjust limits via the Customer API:

curl -X PUT "https://TENANT.api.wocha.ai/v1/customer/settings/sms" \
  -H "Authorization: Bearer wocha_mgmt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "per_phone_limit": 5,
    "daily_limit": 2000
  }'

Step 6 — Send a test SMS

1. In Settings → SMS, scroll to Test delivery
2. Enter a phone number in E.164 format (e.g. +447911123456)
3. Click Send test SMS

A test OTP is sent using your configured primary provider. Check the delivery dashboard for the result. If the primary fails, failover to the secondary provider is attempted automatically.

Step 7 — Monitor delivery

The SMS Delivery Dashboard (under Settings → SMS or Risk & Fraud) shows:

• Delivery success/failure rate (24h, 7d, 30d)
• Per-provider delivery statistics
• Failed deliveries table (timestamp, phone hash, provider, error code)
• Monthly SMS volume

Delivery logs store hashed phone numbers (recipient_hash) — not plaintext E.164 values.

Self-hosted configuration

For self-hosted deployments, SMS provider credentials are stored in tenant_configs under the sms key. The SMS Gateway package (@wocha/sms-gateway) reads this configuration at runtime. Ensure Valkey is available for OTP storage and rate limiting.

Kratos SMS courier (for native login/recovery codes) requires separate TWILIO_* environment variables on the Kratos service. See SMS authentication for Kratos courier setup.

Related

• SMS authentication guide — architecture and security
• Phone API reference — Account API phone endpoints
• SMS MFA API reference — MFA enrolment endpoints
• Adaptive MFA — phone risk signals at consent time