API & Integrations

Send your first SMS with the WebSMS API

Create API credentials, get an access token, send a test and a real SMS with curl, and check delivery - in about five minutes.

Updated 4 min read

The WebSMS API lets your website, app or system send texts automatically, for things like booking confirmations, passcodes and alerts. This guide takes you from zero to your first sent message in about five minutes: create API credentials, get an access token, send a message and check it was delivered.

You’ll need: a WebSMS account with some credit, and a way to make HTTP requests. The examples use curl, which works in any terminal. Full reference: API documentation and the OpenAPI explorer.

1. Create your API credentials

  1. Open API Keys. Click your name in the top-right corner, then API Keys.
  2. Name the key after where it will be used, e.g. My website, then click Create API Key.
  3. Copy both values now. You’ll see a Client ID (starts with cid_) and a Client Secret (starts with csk_). The secret is shown only once, so store it in your app’s secret settings or password manager.
Create New API Key form with a key name entered and the Create API Key button
Create a key for each app or environment so you can revoke one without affecting the others

Keep the secret secret. Never put it in website JavaScript, a mobile app or a public code repository. Call the API from your server. If a secret leaks, click Regenerate Secret on that key, which immediately cancels the old one.

2. Get an access token

Swap your Client ID and Secret for an access token. A token lasts 24 hours, so get a new one when it expires rather than for every message.

curl -X POST https://api.websms.co.nz/api/connexus/auth/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{"access_token":"wst_...","token_type":"Bearer","expires_in":86400}

3. Try a test send (sandbox)

Add sandbox=true to check your request without sending anything or spending credit. The response tells you the encoding, how many segments the message uses and what it would cost.

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "to=6421234567" \
  -d "body=Hi Sam, your booking is confirmed for 10am tomorrow." \
  -d "messageClass=transactional" \
  -d "sandbox=true"

4. Send your first real SMS

Remove sandbox=true and use your own mobile number for the first send:

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "to=6421234567" \
  -d "body=Hi Sam, your booking is confirmed for 10am tomorrow." \
  -d "messageClass=transactional" \
  -d "messageId=booking-1042"

A successful send returns HTTP 200:

{"success":true,"status":"accepted","message_id":1188236,"to":"6421234567","from":"2190","parts":1}
FieldWhat to send
toMobile number in international format without +, e.g. 6421234567. A leading 0 is treated as an NZ number.
bodyMessage text. Up to 160 characters is one SMS; longer messages are split into 153-character parts, up to 11 parts.
messageClasstransactional or marketing. See which one applies.
messageIdOptional. Your own reference (up to 36 characters), returned in status checks and webhooks.
fromOptional. Your dedicated shortcode, if you have one. Leave it out to use the shared shortcode.

5. Check it was delivered

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

The status will be DELIVRD once the phone has received it. Other values include ACCEPTD/PENDING (on its way), UNDELIV/FAILED (not delivered) and BLOCKED. See what each delivery status means.

Rather than polling, set a Webhook URL on the API Keys page. WebSMS will then POST delivery receipts (type: "dlr") and incoming replies (type: "SMS") to your server as they happen.

Common first-send problems

ResponseWhat it meansFix
401 Invalid or expired tokenThe token is wrong or more than 24 hours oldRequest a new token (step 2)
403 Insufficient fundsNot enough credit for the messageAdd funds
422 url_not_whitelistedThe message contains a link that isn’t approved. It was rejected and a small fee charged.Get the domain whitelisted, then resend
429 duplicate_loop_protectionThe same message was sent to the same number more than 3 times in 10 minutesCheck your code isn’t retrying in a loop. Nothing was sent or charged.
429 recipient_rate_limitMore than 15 messages to one number in an hourSlow down, or ask support about your use case
400 Destination country not permittedYour account restricts which countries you can send toUpdate Allowed Destination Countries on the API Keys page

A 200 isn’t always delivered. If the recipient has opted out, or the number is invalid, the request still returns success but the message is BLOCKED. Always use the status query or your webhook to confirm delivery. See opted-out numbers.

Good to know

  • Night-time hold: transactional messages to NZ numbers submitted between 11pm and 7am NZ time are queued and sent at 7am (response status: "queued"). Passcodes sent through the OTP endpoint (sms/otp) are exempt. See night-time sending and 24/7 exemptions.
  • Bulk: send a JSON body with to as an array to message up to 200 numbers in one request.
  • Using a framework or no-code tool? There’s a Laravel package, ready-made integrations for Zapier, Make, HubSpot and more, and an MCP server for AI assistants.
  • Sending one-time passcodes? See OTP SMS for NZ, which has code samples.
Still need a hand?

We’re a small New Zealand team and happy to help.