WebSMS Connexus API

The Connexus API supports two authentication methods:

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "body=Hello" \
  -d "messageClass=transactional"

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!

Step 2: Get an Access Token

Exchange your client credentials for an access token:

curl -X POST https://api.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://api.websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer wst_abc123..." \
  -d "to=6421234567" \
  -d "body=Hello World" \
  -d "messageClass=transactional"

Token Endpoint Details

Error Responses:

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

To help protect recipients from phishing and spam, all links in outbound messages are checked against your account's list of approved domains. Messages containing links to a domain that hasn't been whitelisted will be held until the domain is approved.

Whitelisting is done within our portal — open the Request whitelist form, enter your domain, and submit. Once approved, messages containing links to that domain are sent immediately.

• Whitelisting applies to the domain (e.g. example.com), so you only need to request each domain once — not every individual URL.
• Request whitelisting before you start sending, so your first campaign isn't delayed waiting for approval.

This is a quiet-hours restriction applied for you so that sending stays within the Appropriate Timing requirement of our Terms of Service — messages should reach recipients at reasonable hours. Nothing is lost or rejected: the API still accepts the request and returns a message ID you can track as normal.

Response for a queued message

{
  "success": true,
  "status": "queued",
  "message_id": "1158493",
  "to": "6421234567",
  "from": "552",
  "parts": 1,
  "queue_reason": "nighttime",
  "queue_message": "Message queued for delivery at 7am NZ time"
}

Check for status: "queued" rather than status: "accepted" if your integration needs to distinguish the two. Delivery reports for a queued message arrive after it is released, not at submission time.

What is and isn't affected

• New Zealand numbers only. The restriction is applied to destinations starting 64. International destinations are never night-queued, so send those according to the recipient's own local time.
• OTP / 2FA codes are exempt. Sends to /api/connexus/sms/otp bypass the queue entirely and go out immediately, day or night — a login code is useless the next morning.
• Everything else is queued, including appointment reminders and transactional messages. messageClass does not change this.

Opt-outs on your own shortcode

On our shared shortcodes we handle opt-outs for you: an inbound STOP (or any of the accepted opt-out keywords) blocks that number on your account automatically, and you can read the list back via Query Blocked Numbers.

Send your first SMS in seconds:

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "body=Hello World" \
  -d "messageClass=transactional"

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "body=Hello World" \
  -d "messageClass=transactional"

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.

Every send must declare a messageClass so we can route it over the appropriate shortcode. Choose the value that matches the intent of the message:

Classifying marketing traffic correctly improves deliverability and keeps your transactional messages on high-trust routes. Misclassifying marketing traffic as transactional may be treated as a compliance issue.

Add sandbox=true to any request to /sms/out, /sms/otp, or /sms/appointment to validate your integration without actually sending an SMS. In sandbox mode WebSMS will:

• Authenticate your credentials and validate all parameters (you still get real 400/401/403 errors for bad inputs or unauthorised shortcodes)
• Echo back the exact message body we received after smart-quote / GSM-7 conversion and any fragmentationLimit truncation, so you can confirm what would have been sent
• Return the detected encoding, message parts, and what the send would have cost
• Respond with a SANDBOX_ message ID and "sandbox": true

Nothing is queued, sent, logged to your message history, or billed to your account. Balance is not checked, so sandbox requests work even with a zero balance.

Example Request:

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "body=Hello from sandbox" \
  -d "messageClass=transactional" \
  -d "sandbox=true"

Example Response:

{
  "success": true,
  "status": "sandbox",
  "message_id": "SANDBOX_671e4d8a9f3c2",
  "to": "6421234567",
  "from": "2190",
  "parts": 1,
  "sandbox": true,
  "sandbox_message": "Hello from sandbox",
  "sandbox_encoding": "GSM-7",
  "sandbox_would_charge": 0.092
}

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

How It Works

Your webhook receives POST requests with JSON payloads. Check the type field to determine which event occurred:

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

{
  "type": "SMS",
  "messageId": "987654",
  "connexusMessageId": "MO6a1b2c3d4e5f",
  "from": "+6421234567",
  "to": "shortcode",
  "body": "Reply text",
  "timestamp": 1234567890,
  "encoding": "text/plain",
  "network": "carrier_name"
}

{
  "type": "dlr",
  "messageId": "987654",
  "connexusMessageId": "MSG6a1b2c3d4e5f",
  "status": "DELIVRD",
  "statusCode": 1,
  "timestamp": 1234567890,
  "details": {
    "smsc": "carrier_name",
    "smscid": "abc12345-6789-def0-1234-56789abcdef0"
  }
}

Delivery Status Codes

Example Webhook Handlers

• PHP
• Node.js
• Python

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

if (($data['type'] ?? '') === 'SMS') {
    // 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 === 'SMS') {
    // 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.get('type') == 'SMS':
        # Incoming SMS
        print(f"SMS from {data['from']}: {data['body']}")
    elif data.get('type') == 'dlr':
        # Delivery report
        print(f"Message {data['messageId']}: {data['status']}")

    return jsonify({'success': True})

if __name__ == '__main__':
    app.run(port=3000)

Query received mobile-originated messages with filters and pagination:

curl -X POST https://api.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"

curl -X POST https://api.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:

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"
  }
}

Example Implementation (PHP):

<?php
// Query incoming messages
$ch = curl_init('https://api.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";
}
?>

Look up delivery status of sent messages:

Three ways to query. Looking up by message ID works for messages of any age; browsing with filters is limited to the current calendar month.

curl -X POST https://api.websms.co.nz/api/connexus/sms/status/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "message_id=1188236,1188240"

curl -X POST https://api.websms.co.nz/api/connexus/sms/status/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "messageId=PRAC-042-7731"

curl -X POST https://api.websms.co.nz/api/connexus/sms/status/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "status=UNDELIV" \
  -d "start_date=2026-08-01 09:00:00" \
  -d "end_date=2026-08-30" \
  -d "limit=50" \
  -d "page=1"

{
  "status": "success",
  "messages": [
    {
      "message_id": "1188236",
      "to": "6421234567",
      "from": "2190",
      "status": "DELIVRD",
      "statusCode": 1,
      "sentTime": "2026-08-30 10:15:22",
      "statusTime": "2026-08-30 10:15:31",
      "customerMessageId": "PRAC-042-7731"
    }
  ],
  "notFound": []
}

Reconcile monthly billing, grouped by rateCode:

If you send on behalf of your own customers, tag each send with a rateCode (e.g. your customer number) and use this endpoint at the end of the month to see exactly what each rateCode was billed. Reports actual billed transactions, so multi-part messages are counted in segments and the amounts always reconcile with your WebSMS account balance.

curl -X POST https://api.websms.co.nz/api/connexus/billing/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "month=2026-08"

{
  "status": "success",
  "rateCodes": [
    {
      "rateCode": "CUST-0042",
      "sendType": "sms",
      "messages": 1250,
      "segments": 1311,
      "amount": 91.77,
      "gst": 13.7655,
      "totalInclGst": 105.5355
    },
    {
      "rateCode": "CUST-0042-OTP",
      "sendType": "otp",
      "baseRateCode": "CUST-0042",
      "messages": 340,
      "segments": 340,
      "amount": 27.20,
      "gst": 4.08,
      "totalInclGst": 31.28
    },
    {
      "rateCode": "CUST-0042-APPT",
      "sendType": "appointment",
      "baseRateCode": "CUST-0042",
      "messages": 95,
      "segments": 102,
      "amount": 8.16,
      "gst": 1.224,
      "totalInclGst": 9.384
    },
    {
      "rateCode": "untagged",
      "sendType": "sms",
      "messages": 18,
      "segments": 18,
      "amount": 1.26,
      "gst": 0.189,
      "totalInclGst": 1.449
    }
  ],
  "totals": {
    "messages": 1703,
    "segments": 1771,
    "amount": 128.39,
    "gst": 19.2585,
    "totalInclGst": 147.6485
  },
  "filters": {
    "rateCode": null,
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-08-31 23:59:59"
  }
}

Fetch numbers that have opted out (STOP/END) from your account:

The same list as Members Area » Blocked Numbers. Use since to poll for changes only — a repeat STOP refreshes blockedAt, and with include=all resubscribed numbers come back with active: false so you can unblock them on your side too.

curl -X POST https://api.websms.co.nz/api/connexus/unsubscribes/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "since=2026-08-30 00:00:00" \
  -d "include=all"

{
  "status": "success",
  "numbers": [
    {
      "number": "6421234567",
      "keyword": "STOP",
      "blockedAt": "2026-08-30 14:22:10",
      "active": true,
      "shortcode": "2190"
    },
    {
      "number": "6427654321",
      "keyword": "STOP",
      "blockedAt": "2026-08-27 09:15:02",
      "active": false,
      "resubscribedAt": "2026-08-30 09:01:44"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "totalRecords": 2, "totalPages": 1 }
}

Query your account balance before sending messages:

curl -X POST https://api.websms.co.nz/api/connexus/sms/balance \
  -H "Authorization: Bearer wst_your_token..."

curl -X POST https://api.websms.co.nz/api/connexus/sms/balance \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword"

Response Format:

{
  "balance": "125.50",
  "currency": "NZD"
}

Example Implementation (PHP):

<?php
// Check account balance
$ch = curl_init('https://api.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:

curl -X POST https://api.websms.co.nz/api/connexus/sms/otp \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "msgCompany=MyApp"

curl -X POST https://api.websms.co.nz/api/connexus/sms/otp \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "msgCompany=MyApp"

Parameters:

Message Format:

{msgCode} is your {msgCompany} verification code{msgComment}
[\n@{webOtpDomain} #{msgCode}]    ← only if webOtpDomain is supplied

Examples:
- "426817 is your MyApp verification code"
- "426817 is your MyApp verification code. Valid for 5 minutes."
- "426817 is your MyApp verification code. Valid for 5 minutes.
   @example.com #426817"

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
}

Example Implementation:

• PHP
• Node.js
• Python
• C#

<?php
// Send OTP code
function sendOTP($phone, $company) {
    $ch = curl_init('https://api.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://api.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://api.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://api.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:

curl -X POST https://api.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"

curl -X POST https://api.websms.co.nz/api/connexus/sms/appointment \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "msgCompany=Sunrise Wellness Clinic"

Parameters:

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://api.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:

curl -X POST https://api.websms.co.nz/api/connexus/number/lookup \
  -H "Authorization: Bearer wst_your_token..." \
  -d "number=0211234567"

curl -X POST https://api.websms.co.nz/api/connexus/number/lookup \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "number=0211234567"

Parameters:

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:

Example Implementation (PHP):

<?php
// Lookup a phone number
$ch = curl_init('https://api.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";
}
?>

Alternative method to configure all webhooks at once:

# Get current configuration
curl -X GET https://api.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://api.websms.co.nz/api/connexus/configure \
  -H "Authorization: Bearer wst_your_token..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://yoursite.com/webhook"
  }'

# Get current configuration
curl -X GET https://api.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://api.websms.co.nz/api/connexus/configure \
  -u "user@domain.co.nz:password" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://yoursite.com/webhook"
  }'

• PHP
• Python
• Node.js
• C#

<?php
// Step 1: Get access token
$ch = curl_init('https://api.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://api.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";
?>

<?php
$url = 'https://api.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";
}
?>

import requests

# Step 1: Get access token
token_response = requests.post(
    'https://api.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://api.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}")

import requests

url = 'https://api.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}")

const axios = require('axios');

async function sendSMS() {
    // Step 1: Get access token
    const tokenRes = await axios.post(
        'https://api.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://api.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));

const axios = require('axios');

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

axios.post('https://api.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 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://api.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://api.websms.co.nz/api/connexus/sms/out", smsContent);

Console.WriteLine(smsRes.IsSuccessStatusCode ? "Sent!" : $"Error: {smsRes.StatusCode}");

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://api.websms.co.nz/api/connexus/sms/out",
    content
);

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

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

Endpoint Mapping

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