Skip to content

Instantly share code, notes, and snippets.

@dansleboby

dansleboby/docs.md

Created February 27, 2026 15:01
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save dansleboby/e894efb2b8dba33bd0f8ef2c0b21ca1d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save dansleboby/e894efb2b8dba33bd0f8ef2c0b21ca1d to your computer and use it in GitHub Desktop.
Download ZIP
VOIP.MS - Docs
Raw
docs.md

VoIP.ms SMS/MMS REST API — Developer Guide

A complete reference for integrating SMS and MMS messaging through the VoIP.ms REST/JSON API. Written for developers with no prior REST API experience.

Table of Contents

  1. What is a REST API?
  2. Account Setup & Credentials
  3. Making Your First API Call
  4. Authentication & Security
  5. API Reference — SMS/MMS Functions
  6. Inbound SMS — URL Callback (Webhook)
  7. Error Handling
  8. Rate Limits & Regulations
  9. Code Examples

1. What is a REST API?

A REST API lets your application talk to a remote server over HTTP — the same protocol your browser uses. You send a request to a URL with parameters, and the server responds with structured data (JSON).

Key concepts:

  • Endpoint: The URL you send requests to. For VoIP.ms: https://voip.ms/api/v1/rest.php
  • Parameters: Key-value pairs you send with your request (credentials, method name, filters).
  • Response: A JSON object containing a status field and the requested data.
  • Methods: GET (parameters in URL) or POST (parameters in request body). VoIP.ms supports both.

Example request (GET):

https://voip.ms/api/v1/rest.php?api_username=you@email.com&api_password=yourpass&method=getIP

Example response:

{
  "status": "success",
  "ip": "203.0.113.42"
}

2. Account Setup & Credentials

Before making any API call, you must complete these steps in the VoIP.ms customer portal.

Step 1 — Set an API Password

  1. Log in to voip.ms
  2. Navigate to Main Menu → SOAP & REST/JSON API
  3. Enter a password dedicated to API access (this is separate from your login password)
  4. Click Save API Password

Step 2 — Enable the API

  1. Same page: Main Menu → SOAP & REST/JSON API
  2. Click Enable/Disable API to turn it on

Step 3 — Whitelist Your IP Address

By default, no IP can access the API. You must explicitly allow your server's IP.

  1. Same page: Main Menu → SOAP & REST/JSON API
  2. Enter the IP address(es) your application will call from
  3. Click Save IP Addresses

Supported formats:

Format Example
Single IP 203.0.113.42
Multiple IPs 203.0.113.42, 203.0.113.43
CIDR range 203.0.113.0/24
Wildcard 203.0.113.*
DNS hostname myserver.example.com

Don't know your IP? Call the getIP method — it's the only function that works without IP whitelisting:

https://voip.ms/api/v1/rest.php?method=getIP

Your Credentials

Every API call requires two parameters:

Parameter Value
api_username Your VoIP.ms login email
api_password The API password you set in Step 1 (not your portal password)

3. Making Your First API Call

Base URL

https://voip.ms/api/v1/rest.php

All functions are called by passing method=<functionName> as a parameter to this single endpoint.

GET Request

Parameters go directly in the URL query string:

https://voip.ms/api/v1/rest.php?api_username=you@email.com&api_password=yourpass&method=getSMS&from=2025-01-01&to=2025-01-31

POST Request

Parameters go in the request body as form data:

curl -X POST https://voip.ms/api/v1/rest.php \
  -d "api_username=you@email.com" \
  -d "api_password=yourpass" \
  -d "method=getSMS" \
  -d "from=2025-01-01" \
  -d "to=2025-01-31"

JSON Content-Type

By default, the response Content-Type is text/html. To get application/json, add:

&content_type=json

Response Structure

Every response contains a status field:

// Success
{ "status": "success", "sms": [...] }

// Error
{ "status": "invalid_credentials" }

Always check status === "success" before processing data.

4. Authentication & Security

  • Never expose credentials in client-side code. Always call the VoIP.ms API from a backend server.
  • API password is separate from your portal login password.
  • IP whitelisting is mandatory — requests from non-whitelisted IPs are rejected with ip_not_enabled.
  • If the API is disabled on your account, you'll get api_not_enabled.
  • Invalid username/password returns invalid_credentials.
  • There is a per-minute request limit; exceeding it returns api_limit_exceeded.

5. API Reference — SMS/MMS Functions

getDIDsInfo

Retrieves information about your DID numbers, including SMS capability and configuration.

Use this to: discover which DIDs support SMS, check if SMS is enabled, and read SMS settings.

Parameter Required Description Example
client No Reseller Client ID or Sub Account 561115 or 100001_VoIP
did No Specific DID number 5551234567

Request:

method=getDIDsInfo

Response (relevant SMS fields):

{
  "status": "success",
  "dids": [
    {
      "did": "5551234567",
      "description": "MIAMI, FL",
      "routing": "account:100001_VoIP",
      "sms_available": "1",
      "sms_enabled": "1",
      "sms_email": "john.doe@example.com",
      "sms_email_enabled": "1",
      "sms_forward": "2264836086",
      "sms_forward_enabled": "1",
      "sms_url_callback": "http://myurl.com",
      "sms_url_callback_enabled": "1",
      "sms_url_callback_retry": "1",
      "smpp_enabled": "1",
      "smpp_url": "http://myurl.com",
      "smpp_user": "",
      "smpp_pass": ""
    }
  ]
}

Key fields:

Field Type Meaning
sms_available "0" / "1" Whether the DID supports SMS at all
sms_enabled "0" / "1" Whether SMS is currently enabled on this DID
sms_url_callback string The URL that receives inbound SMS notifications
sms_url_callback_enabled "0" / "1" Whether the callback is active
sms_url_callback_retry "0" / "1" Whether failed callbacks are retried

Filtering SMS-capable DIDs: iterate over the dids array and check sms_available === "1".

setSMS

Enable/disable SMS on a DID and configure SMS delivery settings (email, forwarding, webhook, callback).

Parameter Required Description Values
did Yes DID to configure 5551234567
enable Yes Enable/disable SMS 1 = enable, 0 = disable
email_enabled No Forward SMS to email 1 / 0
email_address No Email to receive SMS you@example.com
sms_forward_enable No Forward SMS to phone 1 / 0
sms_forward No Phone number to forward to 5551234567
url_callback_enable No Enable URL callback 1 / 0
url_callback No URL for inbound SMS webhook See Section 6
url_callback_retry No Retry on failed callback 1 / 0
webhook_enable No Enable 3CX/PortSIP webhook 1 / 0
webhook No 3CX/PortSIP webhook URL URL string
dialmode No Dialing mode 1 = NANPA (10-digit), 2 = E164 (+1 prefix)
smpp_enabled No Enable SMPP delivery 1 / 0
smpp_url No SMPP server URL smpp://host:port or ssmpp://host:port
smpp_user No SMPP username string
smpp_pass No SMPP password string
sms_sipaccount_enabled No Send SMS to SIP account 1 / 0
sms_sipaccount No SIP account name 100001_VoIP

Request:

method=setSMS&did=5551234567&enable=1&url_callback_enable=1&url_callback=https://myapp.com/sms/inbound?to={TO}&from={FROM}&message={MESSAGE}

Response:

{ "status": "success" }

Important: After enabling/disabling SMS, wait at least 1 minute before trying again. Calling too quickly returns sms_wait_message.

getSMS

Retrieve SMS messages with optional filters.

Parameter Required Description Example
sms No Specific SMS ID 5853
from No Start date (default: today) 2025-01-01
to No End date (default: today) 2025-01-31
type No Message direction 1 = received, 0 = sent
did No Filter by DID 5551234567
contact No Filter by contact number 5551234568
limit No Max records (default: 50) 100
timezone No Timezone offset -5 (EST)
all_messages No Include MMS too (sms ID must be 0) 1 = all, 0 = SMS only

Request:

method=getSMS&from=2025-01-01&to=2025-01-31&did=5551234567&limit=100

Response:

{
  "status": "success",
  "sms": [
    {
      "id": "111120",
      "date": "2025-01-15 10:24:16",
      "type": "0",
      "did": "5551234567",
      "contact": "5551234568",
      "message": "Hello from VoIP.ms",
      "carrier_status": "Information not available"
    }
  ]
}

Field reference:

Field Description
id Unique message ID (use for deleteSMS)
date Timestamp YYYY-MM-DD HH:MM:SS
type "0" = sent, "1" = received
did Your DID number
contact The other party's number
message Message body (URL-encoded; + = space)
carrier_status Delivery status from carrier

No messages? The API returns no_sms when no messages match your filters.

getMMS

Retrieve MMS messages. Works identically to getSMS but includes media URLs.

Parameter Required Description Example
mms No Specific MMS ID 1918
from No Start date (default: today) 2025-01-01
to No End date (default: today) 2025-01-31
type No Direction 1 = received, 0 = sent
did No Filter by DID 5551234567
contact No Filter by contact number 5551234568
limit No Max records (default: 50) 100
timezone No Timezone offset -5
all_messages No Include SMS too (mms ID must be 0) 1 = all, 0 = MMS only

Response:

{
  "status": "success",
  "sms": [
    {
      "id": "111120",
      "date": "2025-01-15 10:24:16",
      "type": "0",
      "did": "5551234567",
      "contact": "5551234568",
      "message": "Check this photo",
      "carrier_status": "Information not available",
      "col_media1": "https://voip.ms/media.php?map=MTU5MzUzMDcTk2NNUw==",
      "col_media2": "",
      "col_media3": "",
      "media": [
        "https://voip.ms/media.php?map=MTU5MzUzMDcTk2NNUw==",
        "",
        ""
      ]
    }
  ]
}

Up to 3 media attachments per MMS (col_media1 through col_media3, also available as the media array).

getMediaMMS

Retrieve media files for a specific MMS message.

Parameter Required Description Example
id Yes MMS message ID 1918
media_as_array No Return format 1 = array, 0 = JSON object (default)

Response:

{
  "status": "success",
  "id": "272377221",
  "date": "2025-01-15 10:24:16",
  "media": [
    "https://voip.ms/media.php?map=MTU5MzUzMDcTk2NNUw==",
    "",
    ""
  ]
}

sendSMS

Send an SMS message (max 160 characters).

Parameter Required Description Example
did Yes Your DID (sender) 5551234567
dst Yes Destination number 5551234568
message Yes Message text (max 160 chars) Hello from my app

Request:

method=sendSMS&did=5551234567&dst=5551234568&message=Hello+from+my+app

Response:

{
  "status": "success",
  "sms": "23434"
}

The sms field contains the ID of the sent message.

sendMMS

Send an MMS message with optional media (max 2048 characters for text).

Parameter Required Description Example
did Yes Your DID (sender) 5551234567
dst Yes Destination number 5551234568
message Yes Message text (max 2048 chars) Check this out
media1 No Media URL or base64 https://example.com/photo.jpg
media2 No Media URL or base64 data:image/png;base64,iVBORw0K...
media3 No Media URL or base64 (empty)

Media limits:

Method Format Size Limit
POST Base64 ~1.2 MB per file
GET Base64 ~160 KB total (URL length limit of 512 chars)
GET or POST URL No API-side limit

Response:

{
  "status": "success",
  "mms": "23434"
}

deleteSMS

Delete a specific SMS message.

Parameter Required Description Example
id Yes SMS message ID 1918

Request:

method=deleteSMS&id=1918

Response:

{ "status": "success" }

deleteMMS

Delete a specific MMS message.

Parameter Required Description Example
id Yes MMS message ID 1918

Request:

method=deleteMMS&id=1918

Response:

{ "status": "success" }

6. Inbound SMS — URL Callback (Webhook)

To receive incoming SMS/MMS in real-time, configure a URL callback on your DID using setSMS.

How It Works

  1. Someone sends an SMS to your DID.
  2. VoIP.ms sends a GET request to your configured URL with message data substituted into placeholders.
  3. Your server processes the message and responds with the plain text ok.
  4. If retry is enabled and VoIP.ms doesn't receive ok, it retries every 30 minutes.

URL Template Variables

Variable Description
{FROM} Sender's phone number
{TO} Your DID that received the message
{MESSAGE} Message content

Configuration Example

method=setSMS&did=5551234567&enable=1&url_callback_enable=1&url_callback=https://myapp.com/api/sms/inbound?to={TO}&from={FROM}&message={MESSAGE}&url_callback_retry=1

Your Endpoint Must

  1. Accept GET requests
  2. Read query parameters: to, from, message
  3. Return the plain text string ok (exactly, no quotes, no HTML)

Example Endpoint (Node.js / Express)

app.get('/api/sms/inbound', (req, res) => {
  const { to, from, message } = req.query;
  // Process and store the message
  console.log(`SMS from ${from} to ${to}: ${message}`);
  res.send('ok'); // Required response
});

7. Error Handling

Every response has a status field. If it's not "success", the value is an error code.

SMS/MMS Specific Errors

Error Code Description What To Do
invalid_sms Invalid SMS ID provided Verify the SMS ID exists
invalid_contact Invalid contact number Check the phone number format
invalid_did Invalid DID number Verify the DID belongs to your account
invalid_dst Invalid destination number Check destination format
invalid_from_number Invalid sender number Ensure DID is SMS-enabled
invalid_to_number Invalid destination number Check number format
invalid_date Bad date format Use YYYY-MM-DD
invalid_daterange Range exceeds 92 days Use a shorter date range
message_empty SMS body is empty Provide a non-empty message
sms_toolong SMS exceeds 160 characters Shorten or use sendMMS (2048 chars)
sms_failed SMS was not delivered Retry or check DID/destination validity
sms_wait_message SMS enable/disable cooldown Wait at least 1 minute and retry
sms_apply_regulations Blocked by SMS regulations Contact messaging@voip.ms
limit_reached Daily SMS limit exceeded Default is 100/day; contact VoIP.ms to increase
no_sms No messages found Adjust date range or filters
missing_sms SMS ID not provided Include the id parameter
missing_did DID not provided Include the did parameter

General API Errors

Error Code Description
invalid_credentials Wrong username or API password
ip_not_enabled Your server IP isn't whitelisted
api_not_enabled API is disabled on your account
api_limit_exceeded Too many requests per minute
missing_credentials Username or password not sent
missing_method No method parameter in request
invalid_method Method name doesn't exist
method_maintenance API method temporarily unavailable

Robust Error Handling Pattern

async function callVoipMs(method, params = {}) {
  const url = new URL('https://voip.ms/api/v1/rest.php');
  url.searchParams.set('api_username', process.env.VOIPMS_USER);
  url.searchParams.set('api_password', process.env.VOIPMS_PASS);
  url.searchParams.set('method', method);
  url.searchParams.set('content_type', 'json');

  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined && value !== null && value !== '') {
      url.searchParams.set(key, value);
    }
  }

  const res = await fetch(url.toString());
  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  const data = await res.json();
  if (data.status !== 'success') {
    throw new VoipMsError(data.status, method);
  }
  return data;
}

class VoipMsError extends Error {
  constructor(code, method) {
    super(`VoIP.ms API error: ${code} (method: ${method})`);
    this.code = code;
    this.method = method;
  }
}

8. Rate Limits & Regulations

  • API request limit: There is a per-minute cap on API calls. Exceeding it returns api_limit_exceeded. Implement exponential backoff.
  • SMS daily limit: Default is 100 SMS per day via the API. Contact messaging@voip.ms to request a higher limit and start the A2P verification process.
  • SMS length: Standard SMS is limited to 160 characters. For longer text, use sendMMS which allows 2048 characters.
  • MMS media size: 1.2 MB per file via POST + base64. No limit when sending media by URL.
  • Date range: getSMS and getMMS filters are limited to 92 days per query.
  • setSMS cooldown: Wait at least 60 seconds between enable/disable calls per DID.

9. Code Examples

Node.js — Fetch All SMS-Capable DIDs

const data = await callVoipMs('getDIDsInfo');
const smsDids = data.dids.filter(d => d.sms_available === '1');

for (const did of smsDids) {
  console.log(`${did.did} — SMS: ${did.sms_enabled === '1' ? 'ON' : 'OFF'}`);
}

Node.js — Send an SMS

const result = await callVoipMs('sendSMS', {
  did: '5551234567',
  dst: '5551234568',
  message: 'Hello from my app!'
});
console.log('Sent SMS ID:', result.sms);

Node.js — Import Message History

async function importHistory(did, startDate, endDate) {
  const smsData = await callVoipMs('getSMS', {
    did,
    from: startDate,
    to: endDate,
    limit: '9999',
  });
  return smsData.sms || [];
}

Node.js — Send MMS with Image URL

const result = await callVoipMs('sendMMS', {
  did: '5551234567',
  dst: '5551234568',
  message: 'Check out this image!',
  media1: 'https://example.com/photo.jpg',
});
console.log('Sent MMS ID:', result.mms);

Node.js — Delete a Message

// Delete SMS
await callVoipMs('deleteSMS', { id: '111120' });

// Delete MMS
await callVoipMs('deleteMMS', { id: '222330' });

Quick Reference Card

Action Method Key Params
List all DIDs + SMS info getDIDsInfo (none)
Enable SMS on a DID setSMS did, enable=1
Configure inbound webhook setSMS did, url_callback_enable=1, url_callback
Get SMS history getSMS from, to, did, type, limit
Get MMS history getMMS from, to, did, type, limit
Get MMS media getMediaMMS id
Send SMS sendSMS did, dst, message
Send MMS sendMMS did, dst, message, media1-3
Delete SMS deleteSMS id
Delete MMS deleteMMS id

Base URL: https://voip.ms/api/v1/rest.php Auth: api_username + api_password on every request

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment