SMS API

Send templated SMS messages with VoiceStamp integrations and dynamic content

📱 18 Available Templates: Including VoiceStamp Share SMS (#100), Verification Code (#2), Welcome SMS (#1), and more.→ View all templates

SMS System Features

The SMS API enables you to:

Send templated SMS with dynamic variables
Share VoiceStamps via SMS with access codes
International support with country code handling
Track delivery status and engagement
Manage templates with the admin interface

Base URL

https://voicestamp.vps.webdock.cloud/api/v1/sms

Send SMS with Template

Send an SMS using a predefined template with dynamic variables.

POST /api/v1/sms/send

Request Body

{
  "template_id": "1",
  "recipient_phone": "+1234567890",
  "recipient_name": "John Doe",
  "variables": {
    "sender_name": "Jane",
    "voicestamp_url": "https://voicestamp.app/listen/vst_123",
    "share_code": "ABC123",
    "message": "Check this out!"
  }
}

Parameters

Parameter	Type	Required	Description
template_id	string	No*	ID of the SMS template (use either template_id or template_name)
template_name	string	No*	Name of the SMS template (use either template_id or template_name)
recipient_phone	string	Yes	Phone number with country code (max 20 chars)
recipient_name	string	No	Display name of the recipient
variables	object	No	Key-value pairs for template variables

* Either template_id or template_name must be provided

Send Direct SMS

Send an SMS with custom message content (without using a template).

POST /api/v1/sms/send-direct

{
  "recipient_phone": "+1234567890",
  "message": "Hello! Your VoiceStamp is ready at https://voicestamp.app/listen/vst_123"
}

Maximum message length: 1600 characters

Send Verification Code

Send a 6-digit verification code via SMS for authentication.

POST /api/v1/sms/verification-code

{
  "recipient_phone": "+1234567890",
  "code": "123456"
}

Uses template ID "2" for verification code format.

Template Management

Get All Templates

GET /api/v1/sms/templates

Retrieve a list of all active SMS templates.

Get Single Template

GET /api/v1/sms/templates/{id}

Get details of a specific SMS template by ID.

Create Template

POST /api/v1/sms/templates

{
  "name": "Welcome SMS",
  "message": "Welcome to VoiceStamp, {{first_name}}! Start recording at {{website}}",
  "short_codes_used": ["first_name", "website"],
  "category": "onboarding"
}

Message field is required and limited to 1600 characters.

Update Template

PUT /api/v1/sms/templates/{id}

Update any field of an existing template. All fields are optional.

Delete Template

DELETE /api/v1/sms/templates/{id}

Soft delete a template (sets is_active to false).

Statistics & Reporting

Get SMS Statistics

GET /api/v1/sms/stats

Get SMS usage statistics and metrics.

Get Sent Messages

GET /api/v1/sms/sent-messages?limit=50

Retrieve a list of sent SMS messages with delivery status.

Get Short Codes

Retrieve all available short codes organized by category for use in SMS templates.

GET /api/v1/sms/short-codes

{
  "success": true,
  "data": {
    "user": {
      "first_name": {"description": "Recipient's first name", "example": "John"},
      "phone": {"description": "Recipient's phone", "example": "+61400123456"}
    },
    "auth": {
      "code": {"description": "6-digit verification code", "example": "123456"}
    },
    "voice": {
      "voicestamp_link": {"description": "Voice recording link", "example": "https://voicestamp.vps.webdock.cloud/listen/abc123"},
      "sender_name": {"description": "Person who sent recording", "example": "Jane Smith"}
    }
  }
}

Phone Number Format

Important guidelines for formatting phone numbers in SMS API requests.

Phone Number Requirements

Must include country code (e.g., +1 for US/Canada)
Use international format: +[country code][number]
Remove spaces, dashes, and parentheses
Examples: +12345678901, +447700900123, +61412345678

Country	Code	Example
United States	+1	+12345678901
United Kingdom	+44	+447700900123
Australia	+61	+61412345678
Canada	+1	+15551234567

Example: Share VoiceStamp via SMS

Complete example of sharing a voice recording via SMS.

// JavaScript Example
const shareVoiceStampSMS = async (voiceStampId, recipientPhone) => {
  // First, get the VoiceStamp details
  const vstResponse = await fetch(`/api/v1/voicestamps/${voiceStampId}`, {
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN_HERE',
      'Content-Type': 'application/json'
    }
  });
  
  const voiceStamp = await vstResponse.json();
  
  // Then send the SMS
  const smsResponse = await fetch('/api/v1/sms/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN_HERE',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: 'vst_share_sms',
      recipient_phone: recipientPhone,
      variables: {
        sender_name: 'John',
        voicestamp_url: voiceStamp.data.public_url,
        share_code: voiceStamp.data.share_code,
        message: 'Voice message for you!'
      }
    })
  });
  
  return smsResponse.json();
};

// Usage
shareVoiceStampSMS('vst_123456', '+12345678901');