WebSMS Connexus API

Simple, powerful SMS API for sending messages, receiving replies, and managing delivery reports

Migrating from Bulletin Connect? See our simple 3-step migration guide

Function Endpoint
Get Access Token https://websms.co.nz/api/connexus/auth/token
Send SMS https://websms.co.nz/api/connexus/sms/out
Webhooks (Incoming SMS & Delivery Reports) Configure in Members Area
Query Incoming Messages https://websms.co.nz/api/connexus/mo/query
Check Balance https://websms.co.nz/api/connexus/sms/balance
Send OTP/2FA Code https://websms.co.nz/api/connexus/sms/otp
Appointment Reminder https://websms.co.nz/api/connexus/sms/appointment
Number Validation (IPMS) https://websms.co.nz/api/connexus/number/lookup

The Connexus API supports two authentication methods:

Username/Password
Basic Auth

Simple authentication using your WebSMS email and password. Best for quick testing and simple integrations.

curl -X POST https://websms.co.nz/api/connexus/sms/out \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "body=Hello"
API Keys (OAuth2-style)
Recommended

More secure authentication using client credentials. Best for production applications.

  1. Create an API key in your dashboard
  2. Exchange credentials for an access token
  3. Use the token in your API calls
Learn more

Recommended for production: API keys provide better security than username/password authentication. Your main password stays protected, and you can manage multiple keys with different expiry dates.

Step 1: Create an API Key

Go to API Keys in your dashboard to create a new key. You'll receive:

  • Client ID (cid_xxx...) - Public identifier
  • Client Secret (csk_xxx...) - Keep this secret!
The client secret is only shown once when you create or roll the key. Store it securely!

Step 2: Get an Access Token

Exchange your client credentials for an access token:

curl -X POST https://websms.co.nz/api/connexus/auth/token \
  -d "client_id=cid_abc123..." \
  -d "client_secret=csk_xyz789..."
Response:
{
  "access_token": "wst_abc123...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Step 3: Use the Token

Include the access token in the Authorization header:

curl -X POST https://websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer wst_abc123..." \
  -d "to=6421234567" \
  -d "body=Hello World"
Token Expiry: Access tokens are valid for 24 hours. When expired, request a new token using your client credentials. Your client_id and client_secret don't expire (unless you set an expiry date on the key).

Token Endpoint Details

URL https://websms.co.nz/api/connexus/auth/token
Method POST
Content-Type application/x-www-form-urlencoded or application/json
Error Responses:
HTTP Code Error Description
400 invalid_request Missing client_id or client_secret
401 invalid_client Invalid credentials, key disabled, or key expired
405 method_not_allowed Only POST method is accepted

Key Management Features

  • Multiple keys: Create up to 10 keys per account
  • Key expiry: Set optional expiry dates on keys (we'll remind you 60 and 30 days before)
  • Roll secrets: Regenerate a key's secret without changing the client_id
  • Enable/Disable: Temporarily disable a key without deleting it
  • Usage tracking: See when each key was last used

Send your first SMS in seconds:

Using API Key Token (Recommended)
curl -X POST https://websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "body=Hello World"
Using Username/Password
curl -X POST https://websms.co.nz/api/connexus/sms/out \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "body=Hello World"
Response
{
  "success": true,
  "status": "accepted",
  "message_id": "1158493",
  "to": "6421234567",
  "from": "552",
  "parts": 1,
  "route": "smsc_2degrees",
  "porting": {
    "ported": false,
    "carrier": "2degrees",
    "source": "redis"
  }
}

The route and porting fields are included for NZ numbers when carrier information is available.

Send the same message to multiple recipients in a single API call using JSON body with to as an array:

Limit: Maximum 200 recipients per bulk request. Requests exceeding this limit will be rejected with HTTP 400. Split larger sends into multiple requests.
Request
curl -X POST https://websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer wst_your_token..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["6421111111", "6422222222", "6423333333"],
    "body": "Your appointment is tomorrow at 2pm"
  }'
Response
{
  "success": true,
  "messages": [
    {
      "success": true,
      "status": "accepted",
      "message_id": "1188236",
      "to": "6421111111",
      "from": "552",
      "parts": 1,
      "route": "smsc_vodafone",
      "porting": {"ported": true, "carrier": "One NZ", "source": "redis"}
    },
    {
      "success": true,
      "status": "accepted",
      "message_id": "1188237",
      "to": "6422222222",
      "from": "552",
      "parts": 1,
      "route": "smsc_vodafone"
    },
    {
      "success": true,
      "status": "accepted",
      "message_id": "1188238",
      "to": "6423333333",
      "from": "552",
      "parts": 1,
      "route": "smsc_2degrees"
    }
  ],
  "summary": {
    "total": 3,
    "sent": 3,
    "failed": 0
  }
}

Each message in the messages array has the same format as a single SMS response. The summary provides totals for easy tracking.

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password mypassword
to Required Recipient phone number (international format). For bulk sends, use JSON body with to as an array. 6421234567 or ["6421111111","6422222222"]
body Required Message content Hello World
from Optional Sender ID 552
messageId Optional Unique message identifier (max 36 chars) MSG123456
rateCode Optional Message source identifier CAMPAIGN1
contentType Optional Message type text/plain
fragmentationLimit Optional Maximum SMS parts (0-3) 3
schedule Optional Unix timestamp for scheduled delivery 1735689600

Response Codes

204 Success - Message sent
400 Bad Request - Missing parameters
401 Unauthorized - Invalid credentials
403 Forbidden - Insufficient funds
500 Server Error

Pricing

Standard SMS (160 chars) $0.10 +GST
Multi-part SMS (per part) $0.10 +GST
Unicode SMS (70 chars) $0.10 +GST
GST applies to NZ customers only

Configure a single webhook URL to receive both incoming SMS messages and delivery status updates

Simplified Setup: Configure your webhook URL in the Members Area → API Keys. A single URL receives both incoming messages and delivery reports - check the type field to determine which event occurred.

How It Works

Your webhook receives POST requests with JSON payloads. Each payload includes a type field:

  • "type": "mo" - Incoming SMS message
  • "type": "dlr" - Delivery status report

Incoming SMS Payload

{
  "type": "mo",
  "messageId": "MO456",
  "from": "+6421234567",
  "to": "shortcode",
  "body": "Reply text",
  "timestamp": 1234567890,
  "encoding": "text/plain",
  "network": "carrier_name"
}

Delivery Report Payload

{
  "type": "dlr",
  "messageId": "MSG123",
  "status": "DELIVRD",
  "statusCode": 1,
  "timestamp": 1234567890,
  "details": {
    "smsc": "carrier_name",
    "smscid": "abc123"
  }
}

Delivery Status Codes

statusCode status Description
1DELIVRDMessage delivered successfully
2UNDELIVMessage undeliverable
4QUEUEDMessage expired/queued
8ACCEPTDMessage accepted by network
16UNDELIVMessage undeliverable

Example Webhook Handlers

<?php
// webhook.php - handles both incoming SMS and delivery reports
$data = json_decode(file_get_contents('php://input'), true);

if ($data['type'] === 'mo') {
    // Incoming SMS message
    $from = $data['from'];
    $message = $data['body'];
    error_log("Incoming SMS from {$from}: {$message}");

    // Optionally send a reply
    // sendReply($from, "Thanks for your message!");

} elseif ($data['type'] === 'dlr') {
    // Delivery status report
    $messageId = $data['messageId'];
    $status = $data['status'];

    if ($status === 'DELIVRD') {
        error_log("Message {$messageId} delivered successfully");
    } elseif ($status === 'UNDELIV') {
        error_log("Message {$messageId} failed to deliver");
    }
}

// Always return 200 OK
http_response_code(200);
echo json_encode(['success' => true]);
?>
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const data = req.body;

  if (data.type === 'mo') {
    // Incoming SMS
    console.log(`SMS from ${data.from}: ${data.body}`);
  } else if (data.type === 'dlr') {
    // Delivery report
    console.log(`Message ${data.messageId}: ${data.status}`);
  }

  res.json({ success: true });
});

app.listen(3000);
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json

    if data['type'] == 'mo':
        # Incoming SMS
        print(f"SMS from {data['from']}: {data['body']}")
    elif data['type'] == 'dlr':
        # Delivery report
        print(f"Message {data['messageId']}: {data['status']}")

    return jsonify({'success': True})

if __name__ == '__main__':
    app.run(port=3000)
Requirements:
  • Webhook URL must use HTTPS
  • Should respond with HTTP 200 within 5 seconds
  • Failed webhooks are retried up to 3 times

Query received mobile-originated messages with filters and pagination:

Using API Key Token (Recommended)
curl -X POST https://websms.co.nz/api/connexus/mo/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "from=6421234567" \
  -d "to=551" \
  -d "start_date=2025-01-01" \
  -d "end_date=2025-01-31" \
  -d "limit=100" \
  -d "page=1"
Using Username/Password
curl -X POST https://websms.co.nz/api/connexus/mo/query \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "from=6421234567" \
  -d "to=551" \
  -d "start_date=2025-01-01" \
  -d "end_date=2025-01-31" \
  -d "limit=100" \
  -d "page=1"

Query Parameters:

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password yourpassword
from Optional Filter by sender number 6421234567
to Optional Filter by recipient (shortcode) 551
callback_status Optional Filter by webhook callback HTTP status 200
start_date Optional Start of date range (Y-m-d or Y-m-d H:i:s) 2025-01-01
end_date Optional End of date range (Y-m-d or Y-m-d H:i:s) 2025-01-31
limit Optional Number of results per page (default: 100, max: 200) 100
page Optional Page number for pagination (default: 1) 1

Response Format:

{
  "status": "success",
  "messages": [
    {
      "messageId": "1234",
      "from": "6421234567",
      "to": "551",
      "body": "Reply message text",
      "receivedTime": "2025-01-15 14:30:00",
      "timestamp": 1736948400,
      "relatedMessageId": "5678",        // Optional: only if reply to sent message
      "callbackUrl": "https://...",      // Optional: only if webhook configured
      "callbackStatus": "200",           // Optional: only if webhook called
      "callbackResponse": "OK"           // Optional: only if webhook responded
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "totalRecords": 250,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "filters": {
    "from": "6421234567",
    "to": "551",
    "callback_status": null,
    "start_date": "2025-01-01 00:00:00",
    "end_date": "2025-01-31 23:59:59"
  }
}
Note: Fields like relatedMessageId, callbackUrl, callbackStatus, and callbackResponse only appear in the response if they have values.

Example Implementation (PHP):

<?php
// Query incoming messages
$ch = curl_init('https://websms.co.nz/api/connexus/mo/query');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'from' => '6421234567',
    'start_date' => '2025-01-01',
    'end_date' => '2025-01-31',
    'limit' => 100,
    'page' => 1
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);

    echo "Total messages: " . $data['pagination']['totalRecords'] . "\n";

    foreach ($data['messages'] as $msg) {
        echo "From: {$msg['from']}, Message: {$msg['body']}\n";
    }

    // Fetch next page if available
    if ($data['pagination']['hasNextPage']) {
        // Query with page=2
    }
} else {
    echo "Error: HTTP $httpCode";
}
?>

Query your account balance before sending messages:

Using API Key Token (Recommended)
curl -X POST https://websms.co.nz/api/connexus/sms/balance \
  -H "Authorization: Bearer wst_your_token..."
Using Username/Password
curl -X POST https://websms.co.nz/api/connexus/sms/balance \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword"

Response Format:

{
  "balance": "125.50",
  "currency": "NZD"
}
Note: The balance endpoint only requires authentication credentials. No message parameters are needed.

Example Implementation (PHP):

<?php
// Check account balance
$ch = curl_init('https://websms.co.nz/api/connexus/sms/balance');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);
    echo "Current balance: $" . $data['balance'] . " " . $data['currency'];
} else {
    echo "Error: HTTP $httpCode";
}
?>

Send a one-time verification code for 2FA authentication:

Using API Key Token (Recommended)
curl -X POST https://websms.co.nz/api/connexus/sms/otp \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "msgCompany=MyApp"
Using Username/Password
curl -X POST https://websms.co.nz/api/connexus/sms/otp \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "msgCompany=MyApp"
Auto-generated code: If you don't provide a code, a secure 6-digit code will be generated automatically and returned in the response.
Special pricing: OTP messages are charged at $0.08 + GST per SMS (or your custom rate if lower).

Parameters:

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password yourpassword
to Required Recipient phone number 6421234567
msgCompany Required Your company/app name (shown in message) MyApp
msgCode Optional Custom 4-8 digit code (auto-generated if not provided) 426817
msgComment Optional Additional text appended to message (truncated to fit 160 chars) Valid for 5 minutes.
from Optional Sender ID (default: 552) 552

Message Format:

{msgCode} is your {msgCompany} verification code{msgComment}

Examples:
- "426817 is your MyApp verification code"
- "426817 is your MyApp verification code. Valid for 5 minutes."

Response Format:

{
  "status": "success",
  "message_id": "abc123def456",
  "to": "6421234567",
  "from": "552",
  "code": "426817",      // The OTP code that was sent (store this to verify later!)
  "parts": 1
}
Important: The code field is always returned in the response. You must store this code on your server to verify the user's input later. The code is not stored by WebSMS.

Example Implementation:

<?php
// Send OTP code
function sendOTP($phone, $company) {
    $ch = curl_init('https://websms.co.nz/api/connexus/sms/otp');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
        'userId' => 'user@domain.co.nz',
        'password' => 'yourpassword',
        'to' => $phone,
        'msgCompany' => $company,
        'msgComment' => 'Valid for 5 minutes.'
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $data = json_decode($response, true);

    // Store the code for verification
    $_SESSION['otp_code'] = $data['code'];
    $_SESSION['otp_expires'] = time() + 300; // 5 minutes

    return $data;
}

// Verify OTP code
function verifyOTP($userInput) {
    if (time() > $_SESSION['otp_expires']) {
        return false; // Expired
    }
    return $userInput === $_SESSION['otp_code'];
}

// Usage
$result = sendOTP('6421234567', 'MyApp');
echo "OTP sent! Code: " . $result['code'];
?>
const axios = require('axios');

// In-memory store (use Redis/DB in production)
const otpStore = new Map();

async function sendOTP(phone, company) {
  const response = await axios.post('https://websms.co.nz/api/connexus/sms/otp', {
    userId: 'user@domain.co.nz',
    password: 'yourpassword',
    to: phone,
    msgCompany: company,
    msgComment: 'Valid for 5 minutes.'
  });

  // Store code for verification
  otpStore.set(phone, {
    code: response.data.code,
    expires: Date.now() + 300000 // 5 minutes
  });

  return response.data;
}

function verifyOTP(phone, userInput) {
  const stored = otpStore.get(phone);
  if (!stored || Date.now() > stored.expires) return false;
  if (userInput === stored.code) {
    otpStore.delete(phone);
    return true;
  }
  return false;
}

// Usage
const result = await sendOTP('6421234567', 'MyApp');
console.log('OTP sent! Code:', result.code);
import requests
import time

# In-memory store (use Redis/DB in production)
otp_store = {}

def send_otp(phone, company):
    response = requests.post('https://websms.co.nz/api/connexus/sms/otp', data={
        'userId': 'user@domain.co.nz',
        'password': 'yourpassword',
        'to': phone,
        'msgCompany': company,
        'msgComment': 'Valid for 5 minutes.'
    })
    data = response.json()

    # Store code for verification
    otp_store[phone] = {
        'code': data['code'],
        'expires': time.time() + 300  # 5 minutes
    }

    return data

def verify_otp(phone, user_input):
    stored = otp_store.get(phone)
    if not stored or time.time() > stored['expires']:
        return False
    if user_input == stored['code']:
        del otp_store[phone]
        return True
    return False

# Usage
result = send_otp('6421234567', 'MyApp')
print(f"OTP sent! Code: {result['code']}")
using System.Net.Http;
using System.Text.Json;

public class OtpService
{
    private static Dictionary<string, (string code, DateTime expires)> _store = new();
    private readonly HttpClient _http = new();

    public async Task<string> SendOtpAsync(string phone, string company)
    {
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("userId", "user@domain.co.nz"),
            new KeyValuePair<string, string>("password", "yourpassword"),
            new KeyValuePair<string, string>("to", phone),
            new KeyValuePair<string, string>("msgCompany", company),
            new KeyValuePair<string, string>("msgComment", "Valid for 5 minutes.")
        });

        var response = await _http.PostAsync(
            "https://websms.co.nz/api/connexus/sms/otp", content);
        var json = await response.Content.ReadAsStringAsync();
        var data = JsonSerializer.Deserialize<JsonElement>(json);
        var code = data.GetProperty("code").GetString();

        // Store code for verification
        _store[phone] = (code, DateTime.UtcNow.AddMinutes(5));

        return code;
    }

    public bool VerifyOtp(string phone, string userInput)
    {
        if (!_store.TryGetValue(phone, out var stored)) return false;
        if (DateTime.UtcNow > stored.expires) return false;
        if (userInput == stored.code)
        {
            _store.Remove(phone);
            return true;
        }
        return false;
    }
}

// Usage
var otp = new OtpService();
var code = await otp.SendOtpAsync("6421234567", "MyApp");
Console.WriteLine($"OTP sent! Code: {code}");

Send appointment reminder SMS with dynamic fields:

Using API Key Token (Recommended)
curl -X POST https://websms.co.nz/api/connexus/sms/appointment \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "msgCompany=Sunrise Wellness Clinic" \
  -d "name=Barry" \
  -d "date=28/10/25" \
  -d "time=11:15am" \
  -d "replyY=true" \
  -d "callUs=09-555-1234" \
  -d "address=42 Main Street, Auckland"
Minimal Example (required fields only)
curl -X POST https://websms.co.nz/api/connexus/sms/appointment \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "msgCompany=Sunrise Wellness Clinic"
Smart templating: Only fields you provide are included in the message. Omit any optional field to leave it out of the SMS.
Special pricing: Templated messages are charged at $0.08 + GST per SMS part (or your custom rate if lower).

Parameters:

Parameter Required Description Example
to Required Recipient phone number 6421234567
msgCompany Required Your business/company name Sunrise Wellness Clinic
name Optional Customer's first name (adds "Hi {name}, " prefix) Barry
date Optional Appointment date 28/10/25
time Optional Appointment time 11:15am
replyY Optional If true, adds "Reply Y to confirm" true
callUs Optional Phone number to call for rebooking 09-555-1234
address Optional Business address 42 Main Street, Auckland
from Optional Sender ID (default: your account default) 552

Message Format Examples:

// All fields provided:
Hi Barry, your next appointment with Sunrise Wellness Clinic is on 28/10/25 at 11:15am. Reply Y to confirm or Pls call us on 09-555-1234 to re-book. Our Address: 42 Main Street, Auckland. Std SMS charges apply.

// Without name:
Your next appointment with Sunrise Wellness Clinic is on 28/10/25 at 11:15am. Reply Y to confirm or Pls call us on 09-555-1234 to re-book. Our Address: 42 Main Street, Auckland. Std SMS charges apply.

// Without date/time:
Hi Barry, your next appointment with Sunrise Wellness Clinic is coming up. Reply Y to confirm or Pls call us on 09-555-1234 to re-book. Std SMS charges apply.

// Minimal (company only):
Your next appointment with Sunrise Wellness Clinic is coming up. Std SMS charges apply.

// Without replyY:
Hi Barry, your next appointment with Sunrise Wellness Clinic is on 28/10/25 at 11:15am. Pls call us on 09-555-1234 to re-book. Our Address: 42 Main Street, Auckland. Std SMS charges apply.

Response Format:

{
  "status": "success",
  "message_id": "abc123def456",
  "to": "6421234567",
  "from": "552",
  "message": "Hi Barry, your next appointment with Sunrise Wellness Clinic is on 28/10/25 at 11:15am. Reply Y to confirm or Pls call us on 09-555-1234 to re-book. Our Address: 42 Main Street, Auckland. Std SMS charges apply.",
  "parts": 2
}

Example Implementation (PHP):

<?php
function sendAppointmentReminder($phone, $company, $options = []) {
    $params = [
        'to' => $phone,
        'msgCompany' => $company
    ];

    // Add optional fields if provided
    if (!empty($options['name'])) $params['name'] = $options['name'];
    if (!empty($options['date'])) $params['date'] = $options['date'];
    if (!empty($options['time'])) $params['time'] = $options['time'];
    if (!empty($options['replyY'])) $params['replyY'] = 'true';
    if (!empty($options['callUs'])) $params['callUs'] = $options['callUs'];
    if (!empty($options['address'])) $params['address'] = $options['address'];

    $ch = curl_init('https://websms.co.nz/api/connexus/sms/appointment');
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer wst_your_token...']);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return json_decode($response, true);
}

// Usage examples:
// Full appointment reminder
$result = sendAppointmentReminder('6421234567', 'Sunrise Wellness Clinic', [
    'name' => 'Barry',
    'date' => '28/10/25',
    'time' => '11:15am',
    'replyY' => true,
    'callUs' => '09-555-1234',
    'address' => '42 Main Street, Auckland'
]);

// Minimal reminder
$result = sendAppointmentReminder('6421234567', 'Sunrise Wellness Clinic');

// With name and date only
$result = sendAppointmentReminder('6421234567', 'Sunrise Wellness Clinic', [
    'name' => 'Barry',
    'date' => '28/10/25',
    'time' => '11:15am'
]);
?>

Validate NZ mobile numbers and check carrier portability status:

Using API Key Token (Recommended)
curl -X POST https://websms.co.nz/api/connexus/number/lookup \
  -H "Authorization: Bearer wst_your_token..." \
  -d "number=0211234567"
Using Username/Password
curl -X POST https://websms.co.nz/api/connexus/number/lookup \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "number=0211234567"
Pricing: $0.005 per lookup + GST. Real-time data from the IPMS (Industry Portability Management System).

Parameters:

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password yourpassword
number Required NZ mobile number (local 02x or international 642x format) 0211234567 or 6421234567

Success Response:

{
  "success": true,
  "number": "6421234567",
  "carrier": "Spark",
  "ported": false,
  "original_network": "Spark",
  "current_network": "Spark",
  "network_code": "TCNZ"
}

Error Responses (400 Bad Request):

// Number too short
{
  "success": false,
  "error": "Invalid number",
  "message": "Number too short. NZ mobile numbers must be 9-11 digits (e.g., 021234567)."
}

// Number too long
{
  "success": false,
  "error": "Invalid number",
  "message": "Number too long. NZ mobile numbers must be 9-11 digits (e.g., 021234567)."
}

// Invalid prefix
{
  "success": false,
  "error": "Invalid number",
  "message": "Invalid prefix. NZ mobile numbers must start with 02X (e.g., 021, 022, 027)."
}

// Invalid format
{
  "success": false,
  "error": "Invalid number",
  "message": "Invalid format. NZ mobile numbers must start with 02X (local) or 642X (international)."
}

Response Fields:

Field Description
successWhether the lookup was successful
numberNormalized phone number (international format)
carrierCurrent carrier name (Spark, One NZ, 2degrees, Skinny, etc.)
portedWhether the number has been ported from its original network
original_networkOriginal network based on number prefix
current_networkCurrent network servicing the number
network_codeNetwork operator code (TCNZ, VNZL, TNZD, etc.)

Example Implementation (PHP):

<?php
// Lookup a phone number
$ch = curl_init('https://websms.co.nz/api/connexus/number/lookup');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'number' => '0211234567'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);

    if ($data['success']) {
        echo "Number: " . $data['number'] . "\n";
        echo "Carrier: " . $data['carrier'] . "\n";
        echo "Ported: " . ($data['ported'] ? 'Yes' : 'No') . "\n";
    }
} else {
    echo "Error: HTTP $httpCode";
}
?>
Use Cases: SMS routing optimization, contact database cleaning, fraud prevention, carrier-based cost management, customer verification.

Alternative method to configure all webhooks at once:

Using API Key Token (Recommended)
# Get current configuration
curl -X GET https://websms.co.nz/api/connexus/configure \
  -H "Authorization: Bearer wst_your_token..."

# Set webhook URL (receives both incoming SMS and delivery reports)
curl -X POST https://websms.co.nz/api/connexus/configure \
  -H "Authorization: Bearer wst_your_token..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://yoursite.com/webhook"
  }'
Using Username/Password
# Get current configuration
curl -X GET https://websms.co.nz/api/connexus/configure \
  -u "user@domain.co.nz:password"

# Set webhook URL (receives both incoming SMS and delivery reports)
curl -X POST https://websms.co.nz/api/connexus/configure \
  -u "user@domain.co.nz:password" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://yoursite.com/webhook"
  }'
Webhook Payloads: Your webhook receives both incoming SMS and delivery reports. Check the type field: "mo" for incoming SMS, "dlr" for delivery reports. See the Webhooks section for full payload details and examples.

Using API Keys (Recommended)
<?php
// Step 1: Get access token
$ch = curl_init('https://websms.co.nz/api/connexus/auth/token');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'client_id' => 'cid_your_client_id',
    'client_secret' => 'csk_your_client_secret'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$tokenResponse = json_decode(curl_exec($ch), true);
curl_close($ch);

$accessToken = $tokenResponse['access_token'];

// Step 2: Send SMS with token
$ch = curl_init('https://websms.co.nz/api/connexus/sms/out');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'to' => '6421234567',
    'body' => 'Hello from WebSMS!'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $httpCode == 200 ? "Sent!" : "Error: $httpCode";
?>
Using Username/Password
<?php
$url = 'https://websms.co.nz/api/connexus/sms/out';
$data = [
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'to' => '6421234567',
    'body' => 'Hello from WebSMS!'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 204) {
    echo "Message sent successfully!";
} else {
    echo "Error: HTTP $httpCode";
}
?>
Using API Keys (Recommended)
import requests

# Step 1: Get access token
token_response = requests.post(
    'https://websms.co.nz/api/connexus/auth/token',
    data={
        'client_id': 'cid_your_client_id',
        'client_secret': 'csk_your_client_secret'
    }
)
access_token = token_response.json()['access_token']

# Step 2: Send SMS with token
response = requests.post(
    'https://websms.co.nz/api/connexus/sms/out',
    headers={'Authorization': f'Bearer {access_token}'},
    data={'to': '6421234567', 'body': 'Hello from WebSMS!'}
)

print("Sent!" if response.status_code == 200 else f"Error: {response.status_code}")
Using Username/Password
import requests

url = 'https://websms.co.nz/api/connexus/sms/out'
data = {
    'userId': 'user@domain.co.nz',
    'password': 'yourpassword',
    'to': '6421234567',
    'body': 'Hello from WebSMS!'
}

response = requests.post(url, data=data)

if response.status_code == 204:
    print("Message sent successfully!")
else:
    print(f"Error: HTTP {response.status_code}")
Using API Keys (Recommended)
const axios = require('axios');

async function sendSMS() {
    // Step 1: Get access token
    const tokenRes = await axios.post(
        'https://websms.co.nz/api/connexus/auth/token',
        new URLSearchParams({
            client_id: 'cid_your_client_id',
            client_secret: 'csk_your_client_secret'
        })
    );

    // Step 2: Send SMS with token
    const smsRes = await axios.post(
        'https://websms.co.nz/api/connexus/sms/out',
        new URLSearchParams({ to: '6421234567', body: 'Hello!' }),
        { headers: { Authorization: `Bearer ${tokenRes.data.access_token}` }}
    );

    console.log('Sent!');
}

sendSMS().catch(err => console.error('Error:', err.response?.status));
Using Username/Password
const axios = require('axios');

const data = new URLSearchParams({
    userId: 'user@domain.co.nz',
    password: 'yourpassword',
    to: '6421234567',
    body: 'Hello from WebSMS!'
});

axios.post('https://websms.co.nz/api/connexus/sms/out', data)
    .then(response => {
        if (response.status === 204) {
            console.log('Message sent successfully!');
        }
    })
    .catch(error => {
        console.error('Error:', error.response?.status);
    });
Using API Keys (Recommended)
using System.Net.Http;
using System.Text.Json;

var client = new HttpClient();

// Step 1: Get access token
var tokenContent = new FormUrlEncodedContent(new Dictionary<string, string>
{
    { "client_id", "cid_your_client_id" },
    { "client_secret", "csk_your_client_secret" }
});
var tokenRes = await client.PostAsync(
    "https://websms.co.nz/api/connexus/auth/token", tokenContent);
var tokenJson = JsonDocument.Parse(await tokenRes.Content.ReadAsStringAsync());
var accessToken = tokenJson.RootElement.GetProperty("access_token").GetString();

// Step 2: Send SMS with token
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
var smsContent = new FormUrlEncodedContent(new Dictionary<string, string>
{
    { "to", "6421234567" },
    { "body", "Hello from WebSMS!" }
});
var smsRes = await client.PostAsync(
    "https://websms.co.nz/api/connexus/sms/out", smsContent);

Console.WriteLine(smsRes.IsSuccessStatusCode ? "Sent!" : $"Error: {smsRes.StatusCode}");
Using Username/Password
using System;
using System.Net.Http;
using System.Collections.Generic;

var client = new HttpClient();
var values = new Dictionary<string, string>
{
    { "userId", "user@domain.co.nz" },
    { "password", "yourpassword" },
    { "to", "6421234567" },
    { "body", "Hello from WebSMS!" }
};

var content = new FormUrlEncodedContent(values);
var response = await client.PostAsync(
    "https://websms.co.nz/api/connexus/sms/out",
    content
);

if ((int)response.StatusCode == 204)
{
    Console.WriteLine("Message sent successfully!");
}
else
{
    Console.WriteLine($"Error: {response.StatusCode}");
}

API Support

Our team is here to help with your integration:

  • Free integration assistance
  • Testing credits available
  • Direct technical support

Contact Us

Email: support@websms.co.nz
Phone: +64 27 4909-712
Hours: Monday-Friday, 9am-5pm NZST

If you're moving from Bulletin Connect, switching to WebSMS is straightforward. Our Connexus API is fully compatible - just update three things:

OLD

service.bulletinconnect.net

NEW

websms.co.nz
  1. Username: Your WebSMS email
  2. Password: Your WebSMS password
  3. URL: Change domain only
100% Compatible - No code changes required beyond updating your configuration

Endpoint Mapping

Function Bulletin Connect WebSMS
Send SMS http://service.bulletinconnect.net/api/1/sms/out https://websms.co.nz/api/connexus/sms/out
Receive SMS http://service.bulletinconnect.net/api/1/sms/in https://websms.co.nz/api/connexus/sms/in
Status Updates http://service.bulletinconnect.net/api/1/sms/status https://websms.co.nz/api/connexus/sms/status

Need help with migration? Contact us at support@websms.co.nz - we offer free migration assistance.