📱 SMS Provider Configuration Guide

Learn how to configure SMS providers to send automated text messages from your system.

🔍 What is an SMS Provider?

An SMS provider allows your system to send automated text messages directly to mobile phones.

SMS messages are commonly used for:

Appointment reminders
Payment notifications
One-time passwords (OTP)
Urgent alerts and confirmations

⚙️ How SMS Sending Works

You choose an SMS provider
You enter the provider credentials
The system connects securely to the provider
SMS messages are sent automatically

💡 If no SMS provider is configured, the system will not send SMS messages.

✅ Supported SMS Providers

🟢 Vonage

Reliable · Global coverage · Easy setup

View Setup

🔵 Twilio

🟣 MessageBird

Strong EU coverage · Omnichannel ready

View Setup

⚙️ Custom SMS Provider

Use your own SMS gateway or regional provider

View Setup

🧩 Common SMS Provider Fields (JSON)

Field	Description	Example
`provider`	The SMS service being used	vonage, twilio
`api_key`	Main authentication key	ACxxxxxxxx
`api_secret`	Secondary authentication token	xxxxxxxx
`from`	Sender ID or phone number	SARUTECH
`prefix`	Default country dialing prefix	+44

⬇️ Continue below for step-by-step setup for each SMS provider

🟢 Vonage SMS Provider Setup

Vonage allows you to send SMS messages directly to your customers from the Perfect Management System, enabling fast, reliable, and automated communication.

🔍 Provider Overview

Vonage is a globally trusted communications platform used for transactional SMS messaging. It is ideal for:

Appointment reminders
Payment and billing notifications
Order and service updates
Urgent system alerts

🌐 Official Website: https://www.vonage.com/communications-apis/

Step 1 — Create a Vonage Account

To start sending SMS using Vonage, you must first create a Vonage account.

Visit the Vonage registration page:
https://ui.idp.vonage.com/ui/auth/registration
Complete the registration process
Log in to your Vonage dashboard

⚠️ Your Vonage account must be active and funded to send SMS messages.

Step 2 — Retrieve Your API Key and API Secret

Vonage uses an API Key and API Secret to authenticate SMS requests.

Log in to the Vonage dashboard
Navigate to API Settings
Copy your API Key and API Secret

🔐 Keep your API credentials secure. Do not share them publicly.

Step 3 — Enter Configuration in the JSON Editor

Open your System Settings, navigate to SMS Provider Settings, and click Manage to open the JSON editor.

Paste the following configuration and replace the values with your own:

{
  "provider": "vonage",
  "api_key": "your_vonage_api_key",
  "api_secret": "your_vonage_api_secret",
  "from": "SARUTECH",
  "prefix": "+44"
}

Field	Required	Description
`provider`	Yes	Must be set to vonage
`api_key`	Yes	Your Vonage API Key
`api_secret`	Yes	Your Vonage API Secret
`from`	Yes	Sender name or phone number
`prefix`	Recommended	Default country dialing prefix

📤 Step 4 — Sending SMS Messages

Once configured, SMS messages can be sent directly from the application when performing actions such as:

Sending payment reminders
Notifying customers of updates
Confirming appointments or actions

💡 Important Tips for Sending SMS

Character Limit: SMS messages are limited to 160 characters per segment
International Numbers: Always use international format (e.g. +44)
Compliance: Ensure messages comply with local privacy regulations

❌ Troubleshooting

Verify API Key and API Secret are correct
Ensure your Vonage account has available balance
Confirm the customer has a valid mobile number

↑ Back to Overview Continue to Twilio →

🔵 Twilio SMS Provider Setup

Twilio is one of the most popular SMS providers globally and is widely used by SaaS platforms for reliable, developer-friendly SMS delivery.

🔍 Provider Overview

Twilio provides a powerful API for sending and receiving SMS messages worldwide. It is especially well suited for:

Transactional SMS messages
High reliability and global reach
Applications requiring detailed delivery logs

🌐 Official Website: https://www.twilio.com/sms

Step 1 — Create a Twilio Account

To begin using Twilio for SMS, you must create a Twilio account.

Visit the Twilio signup page:
https://www.twilio.com/try-twilio
Create an account and verify your email address
Complete phone number verification

⚠️ Trial accounts can only send SMS to verified phone numbers.

Step 2 — Get Your Account SID and Auth Token

Twilio uses an Account SID and Auth Token for API authentication.

Log in to the Twilio Console
On the main dashboard, locate:

Account SID
Auth Token

Copy both values and store them securely

💡 In the system JSON configuration:

Account SID → api_key
Auth Token → api_secret

Step 3 — Purchase or Assign a Twilio Phone Number

In the Twilio Console, go to Phone Numbers
Purchase a new SMS-enabled phone number
Ensure SMS capabilities are enabled

⚠️ The from field must be a Twilio-owned phone number.

Step 4 — Enter Configuration in the JSON Editor

Open your System Settings, navigate to SMS Provider Settings, and open the JSON editor.

Paste the following configuration and replace the values with your own:

{
  "provider": "twilio",
  "api_key": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_secret": "your_auth_token_here",
  "from": "+1234567890",
  "prefix": "+44"
}

Field	Required	Description
`provider`	Yes	Must be set to twilio
`api_key`	Yes	Twilio Account SID
`api_secret`	Yes	Twilio Auth Token
`from`	Yes	Twilio phone number (E.164 format)
`prefix`	Recommended	Default country dialing prefix

🧪 Testing Your Twilio Configuration

Save the JSON configuration
Send a test SMS from the application
Check delivery status in the Twilio Console

✅ If configured correctly, SMS messages will be delivered reliably via Twilio.

❌ Common Issues & Fixes

From number invalid → Must be a Twilio-owned number
Permission denied → Trial account limitations
SMS not delivered → Destination number not verified (trial)

← Back to Vonage Continue to MessageBird →

🟣 MessageBird SMS Provider Setup

MessageBird is a powerful cloud communications platform with strong SMS coverage, particularly across Europe and international markets.

🔍 Provider Overview

MessageBird provides reliable SMS delivery with support for both phone-number and alphanumeric sender IDs.

It is ideal for:

Transactional SMS notifications
European and international customers
Businesses planning omnichannel messaging in the future

🌐 Official Website: https://www.messagebird.com

Step 1 — Create a MessageBird Account

Visit the MessageBird signup page:
https://dashboard.messagebird.com/en/sign-up
Create an account and verify your email address
Log in to the MessageBird dashboard

⚠️ Your MessageBird account must be active and funded to send SMS messages.

Step 2 — Get Your API Access Key

MessageBird uses a single Access Key for API authentication.

Log in to the MessageBird dashboard
Go to Developers → API Access
Copy your Live API Key

🔐 Keep your API key secure. Anyone with this key can send SMS messages on your behalf.

Step 3 — Enter Configuration in the JSON Editor

Open your System Settings, navigate to SMS Provider Settings, and open the JSON editor.

Paste the following configuration and replace the values with your own:

{
  "provider": "messagebird",
  "api_key": "live_xxxxxxxxxxxxxxxxxxxxx",
  "from": "SARUTECH",
  "prefix": "+44"
}

Field	Required	Description
`provider`	Yes	Must be set to messagebird
`api_key`	Yes	Your MessageBird Live API Key
`from`	Yes	Sender ID (text or phone number)
`prefix`	Recommended	Default country dialing prefix

📛 Sender ID Rules

Alphanumeric sender IDs may not be supported in all countries
Some regions require sender ID pre-registration
Use a phone number if delivery fails with text sender

🧪 Testing Your MessageBird Configuration

Save the JSON configuration
Send a test SMS from the application
Check delivery logs in MessageBird dashboard

✅ If configured correctly, MessageBird will deliver SMS messages reliably.

❌ Common Issues & Fixes

Unauthorized → API key incorrect
Message not delivered → Sender ID not supported in country
Invalid number → Phone number not in international format

← Back to Twilio Continue to Custom SMS Provider →

⚙️ Custom SMS Provider (Advanced)

This option allows you to integrate any SMS gateway that provides an HTTP API, even if it is not officially listed.

👤 Who Should Use a Custom SMS Provider?

Advanced or technical users
Organisations using a regional SMS gateway
Companies with an internal telecom or messaging platform
Users migrating from legacy SMS systems

⚠️ This option assumes you understand how your SMS provider’s API works.

🔍 How the Custom SMS Provider Works

Internally, the system sends SMS messages by calling a backend API endpoint with the following payload:

{
  "from": "SENDER_ID",
  "to": "+447900000000",
  "message": "Your appointment is confirmed",
  "provider": "custom",
  "api_key": "...",
  "api_secret": "..."
}

When using a custom SMS provider, the system:

Reads your SMS provider JSON configuration
Passes credentials and message details to the backend
Routes the request to a custom provider handler
Sends the SMS using your provider’s API

🧩 Required JSON Fields

Field	Required	Description
`provider`	Yes	Must be set to custom
`api_key`	Usually	Main authentication key for your SMS gateway
`api_secret`	Optional	Secondary token or secret (if required)
`from`	Yes	Sender ID or phone number
`prefix`	Recommended	Default country dialing prefix

📝 Example Custom SMS Provider Configuration

{
  "provider": "custom",
  "api_key": "your-custom-api-key",
  "api_secret": "your-custom-api-secret",
  "from": "COMPANY",
  "prefix": "+44",
  "endpoint": "https://sms.yourprovider.com/send"
}

💡 Additional fields such as endpoint, headers, or route can be stored here for future or custom backend handling.

✅ When to Use a Custom SMS Provider

Your SMS provider is not officially supported
You require regional or telecom-specific routing
You want full control over delivery logic
You plan to extend the backend integration later

🔁 Fallback & Error Behaviour

If a custom provider is misconfigured or fails:

The system will return an error
No SMS will be sent
You can switch providers instantly by editing the JSON

💡 Always test custom providers in a staging environment before production use.

🏁 Best Practices

Use dedicated sender IDs or numbers
Always store API credentials securely
Respect local SMS regulations and opt-in rules
Monitor delivery reports and error responses

← Back to MessageBird ✔ SMS Provider Setup Complete