SMS Service Integrations

Spaaza supports sending SMS messages through multiple SMS providers. SMS is currently used primarily for OTP (One-Time Password) phone number verification rather than for marketing communications. When a chain has phone number verification enabled, Spaaza sends a verification code via SMS to the user's phone number during signup in the Spaaza white-label mobile app or when updating their phone number.

Contents

• Overview
• How SMS Verification Works
• Supported SMS Providers
• Configuring an SMS Provider
• Related API Endpoints

Overview

Spaaza integrates with three SMS providers to deliver OTP verification codes to users:

Provider	Region	Description
Twilio	Global	Global SMS platform; the default provider for most chains
Dergosms	Kosovo	Regional SMS provider available in Kosovo
SMS Localhost	Zimbabwe	Zimbabwean SMS gateway (sms.localhost.co.zw)

Each provider is configured per chain via the webhook configuration system. When a phone number verification event is triggered, the Spaaza event processing service dispatches the SMS to the configured provider for that chain.

How SMS Verification Works

Phone number verification via SMS OTP follows this flow:

1. Enable verification on the chain — set verify_phone_numbers to true on the chain using the alter-chain endpoint.
2. User signs up or updates their phone number — when a user signs up via the Spaaza white-label mobile app or updates their phone number, and the chain has verification enabled, Spaaza generates an OTP code and queues a phone_number_verification event. The OTP code and a verification_code_key are returned in the API response from add-user or alter-user.
3. SMS is sent — the event processing service picks up the event and dispatches the verification code SMS to the user's phone number via the configured SMS provider for that chain.
4. User verifies the code — the client application collects the code from the user and submits it to the otp-verify endpoint (see Authentication) along with the verification_code_key returned from the signup or alter-user response. On successful verification, the user's phone_number_status is set to VERIFIED (3).
5. Requesting a new code — if the original code expires or the user needs a new one, a new OTP can be requested via the otp-request endpoint (see Authentication).

note

The SMS message template is a standard verification template: "Phone number verification: {Code}. This code is valid for a limited time. If you did not request it, ignore this message and ensure your account is secure."

Supported SMS Providers

Spaaza currently supports the following SMS providers. Each provider has its own documentation page with details on credentials, phone number format requirements, and API payload structure:

• Twilio — global cloud communications platform, the default SMS provider used by most Spaaza chains.
• Dergosms — regional SMS provider available in Kosovo for delivering SMS messages.
• SMS Localhost — Zimbabwean SMS gateway (sms.localhost.co.zw), used for phone number verification by Spaaza chains operating in Zimbabwe.

Configuring an SMS Provider

SMS providers are configured through Spaaza's webhook configuration system. To set up an SMS provider for a chain:

1. Enable phone number verification on the chain by setting verify_phone_numbers to true via alter-chain.
2. Create a webhook configuration for the chain with:
   • event_name set to phone_number_verification
   • type set to the provider type (twilio, dergosms, or smslocalhost)
   • The provider-specific credentials (see each provider's documentation page)

Webhook configurations are managed using the following internal API endpoints:

Endpoint	Method	Description
/internal/add-webhook	POST	Create a new webhook configuration
/internal/get-webhook	GET	Retrieve a single webhook configuration
/internal/get-webhooks	GET	List webhook configurations for a chain
/internal/alter-webhook	POST	Update an existing webhook configuration
/internal/delete-webhook	POST	Delete a webhook configuration

note

Webhook configuration endpoints require admin authentication. Contact the Spaaza team if you need assistance configuring an SMS provider for your chain.

Related API Endpoints

The following API endpoints are relevant to SMS-based phone number verification:

Endpoint	Description
add-user	Create a new user. When the chain has phone verification enabled and a phone number is provided, an OTP verification code is sent via SMS.
alter-user	Update a user. When the chain has phone verification enabled and the phone number is changed, an OTP verification code is sent via SMS.
alter-chain	Enable or disable phone number verification on a chain (verify_phone_numbers parameter).
Authentication	OTP endpoints: otp-request (request a new verification code) and otp-verify (verify a code).
Webhooks and Events	Overview of Spaaza's webhook and event notification system.