Last updated: Jun 15th, 2019

API Introduction

This API is designed to integrate complex messaging (SMS, Fax and Text-To-Speech) using simple SOAP tools.


If you don't have an account, you'll need to register one.

Learn more...

You'll need a new Sender/Token combo for your application.

Learn more...

Each type of message has a unique WDSL. You can use one single sender/token pair to send all message types.

Delivery Reports can be provided via a Webhook to your URL, Email, or viewed with the Web Dashboard.

Learn more...

Register your account

Head to https://www.tnz.co.nz/Customer/SignUp/ to create a new account.

A test account is possible, however creating a commercial account and using the Mode=Test function of the API is simpler to use when you’re ready to push your application live.

After completing the sign up form, a sales consultant will manually activate your account. This may take one business day. Once the account has been activated, you will be able to Create a new API user token.


Create a new API user token

Using the API will require a Sender and Token pair to authenticate with the API.

  1. Login to the TNZ Dashboard
  2. Navigate to 'Users'
  3. Create a new user or select an existing one
  4. Enable API access (if it's not already enabled)
  5. Click on the 'API' tab
  6. Enable 'Sender/APIKey' and create a new APIKey
  7. Click the ' Copy' button to copy the API Key to your clipboard
  8. Paste the Sender and APIKey into the relevant section in your application or code

Sender = Sender
APIKey = Token


Understanding the API basics

Each message type (SMS, Fax, TTS) has a unique WDSL URL while keeping to a common theme.

Using the "Send" options, messages can be submitted for sending. Using the "Reporting" options, delivery results and reply messages can be captured.


SOAP URLs:

  • Send SMS: https://www.tnz.co.nz/web/scripts/SendSMS.wsdl

  • Send Fax: https://www.tnz.co.nz/web/scripts/SendFax.wsdl

  • Send Text-to-Speech (Voice): https://www.tnz.co.nz/web/scripts/SendTTS.wsdl

The possible SOAP response values are:

  OK Thanks

  Missing sender

  Missing token

Send SMS/TXT via SOAP

Resources

 

Required parameters

Parameter Example Value Description
sender application@domain.com Sender value set up in Create a new API user token
token ta8wr7ymd Token value set up in Create a new API user token
number 021000001 Destination mobile number in dialling format (02, 0064, +64)
message Hello, this is a test message from Department01. Thank you. Plain or UTF-8 formatted SMS message

Optional parameters

Parameter Example Value Description
messageid ID123456 A message tracking identifier (maximum 40 characters, alphanumeric)
reference Test1 Optional extra tracking ID or message description
smsemailreply person.one@domain.com For email (SMTP) reply receipt notifications

Send Fax via SOAP

 

Required parameters

Parameter Example Value Description
sender application@domain.com Sender value set up in Create a new API user token
token ta8wr7ymd Token value set up in Create a new API user token
number 095005000 Destination fax number in dialling format (09, 0064, +64)
reference Test1 Tracking ID or message description
file_name_1 mydocument.pdf The file name of the fax document to be faxed
file_contents_1 %BASE64% Encoded file contents (specified by file_name_1)

Optional parameters

Parameter Example Value Description
resolution High Sets the resolution of the fax document (higher requires more of the receiver's consumables). Options are 'high' or 'low'
attention Gary Smith The person the fax is addressed to
company Company Name Ltd The company name the fax is addressed to
sendtime 08/12/2020 13:55 Delays delivery until the specified send time (your account's configured local time). Accepted formats are YYYY-MM-DD HH:mm and HH:mm
utcsendtime 08/12/2020 13:55 Same as 'sendtime' but assumes time is UTC (ignores your account's configured local time)
file_name_2 seconddocument.pdf The file name of the document to be faxed
file_contents_2 %BASE64% Encoded file contents (specified by file_name_2)
file_name_3 thirddocument.pdf The file name of the document to be faxed
file_contents_3 %BASE64% Encoded file contents (specified by file_name_3)
file_name_4 fourthdocument.pdf The file name of the document to be faxed
file_contents_4 %BASE64% Encoded file contents (specified by file_name_4)
file_name_5 fifthdocument.pdf The file name of the document to be faxed
file_contents_5 %BASE64% Encoded file contents (specified by file_name_5)

Send Text-To-Speech via SOAP

 

Required parameters

Parameter Example Value Description
sender application@domain.com Sender value set up in Create a new API user token
token ta8wr7ymd Token value set up in Create a new API user token
phone_numbers 095005000, 021000001, 036006000 A list of destination telephone numbers in dialling format (09, 02, 0064, +64)
MessageToPeople Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre. The text-to-speech message played if the call is answered by a human (may optionally include SSML commands)

Optional parameters

Parameter Example Value Description
reference Test1 Tracking ID or message description
message_to_answer_phones Hello, this is a call from Department01. Sorry we missed you. Call us back on 097007000 to discuss further. Message played if an answering machine is detected (non-human answer) (may optionally include SSML commands)
call_route_msg_to_operators Incoming call from TTS service. Message played to the operator when receiving a routed call
call_route_msg_to_people Hold a moment while we connect you to an operator. Message played to listener when call routing begins (after pressing a keypad button)
call_route_msg_on_wrong_key Sorry, that's not a valid keypad option. Please try again. Message played when listener presses a disabled keypad button
csv_list %Base64% CSV list of phone numbers (overrides 'phone_numbers'). Needs a title row "Main Phone" with telephone numbers on subsequent rows
sendtime 08/12/2020 13:55 Delays delivery until the specified send time (your account's configured local time). Accepted formats are YYYY-MM-DD HH:mm and HH:mm
endtime 08/12/2020 14:20 End the call if this time is reached (cuts call)
caller_id 6493334444 The Caller ID used
retry_attempts 2 Should the call fail it is retried x times
retry_period 15 Should the call fail wait x minutes before retrying
voice Female1 The TTS voice used (Male1, Female1, Nicole, Russell, Amy, Brian, Emma)
keypad_1_enabled Yes Enable DTMF #1
keypad_1_route_number 097007000 If keypad 1 is pressed, route the call to this number
keypad_2_enabled Yes Enable DTMF #2
keypad_2_route_number 021000005 If keypad 2 is pressed, route the call to this number
keypad_3_enabled No Enable DTMF #3
keypad_3_route_number If keypad 3 is pressed, route the call to this number
keypad_4_enabled No Enable DTMF #4
keypad_4_route_number If keypad 4 is pressed, route the call to this number
keypad_5_enabled No Enable DTMF #5
keypad_5_route_number If keypad 5 is pressed, route the call to this number
keypad_6_enabled No Enable DTMF #6
keypad_6_route_number If keypad 6 is pressed, route the call to this number
keypad_7_enabled No Enable DTMF #7
keypad_7_route_number If keypad 7 is pressed, route the call to this number
keypad_8_enabled No Enable DTMF #8
keypad_8_route_number If keypad 8 is pressed, route the call to this number
keypad_9_enabled No Enable DTMF #9
keypad_9_route_number If keypad 9 is pressed, route the call to this number
options Miscellaneous functions

Resending and retrying messages

To resend or retry sending a message via the REST API, this will need to be submitted as a new, unique message.
To resend or retry sending a message via the Web Dashboard, once logged in and viewing an individual message, you will see Resubmit and Forward buttons.


Status Reporting - Reporting and event tracking

Delivery Reports advise whether delivery was successful. If not, it will describe why.

Each delivery report type is optional and multiple delivery report types can be used.



Web Dashboard - Tracking message statuses via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.



SMTP Email - Receive message statuses via email

Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.

Whitelabelling of SMTP Email reports is available.

The email address to receive SMS Reply reports can be specified on the original message submission using the SMSEmailReply parameter.



Webhook - Message statuses delivered via a webhook

To receive Delivery Reports via Webhook, please advise the URL to submit to.
Webhooks are provided as an HTTP POST in either XML or JSON format (your preference).

Supplied parameters are:


Parameter Example Value Description
Sender application@domain.com Webhook sender authentication (can configure a unique Sender if required)
Token ta8wr7ymd Webhook token authentication (can configure a unique Token if required)
Type SMS Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', or 'SMSReply')
Destination +6421000001 Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
MessageID js82hn8n MessageID parameter supplied when sending your original API call
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTime 16/10/2018 13:43 p.m. Time message was completed (Sender's local time time in 'dd/MM/yyyy HH:mm tt' format)
Status SUCCESS For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result Sent OK Final delivery result and/or the cause for a message delivery failure
For a list of possible values, see SMS, Fax, Voice, TextToSpeech (Email result codes are defined by the receiving email server)
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message This is a reply. This field will only contain data if 'Type=SMSReply'
Price 0.20 Your cost for this transaction, charged by us to you
Detail SMSParts:2 Additional billing detail: "SMSParts", "FaxPages", "VoiceMinutes", "Size", "Prompts"

GET Status Poll - Track message statuses using a GET poll

API users are able to poll for the status of a message via the GET Status API, as well as capture any SMS replies received.


The GET Poll options are described in the REST API guide:


API Name Description
GET Status Poll Poll for the delivery status of an outbound message (tracked using the MessageID, applies to all message types)
GET Inbound SMS Poll Poll for a list of all SMS received in a given time-frame
GET Received Poll Poll for replies to a specific outbound SMS message (tracked using the MessageID)

Frequently Asked Questions

Yes, full international delivery is supported.
The maximum request size supported is 20MB. This is our server side limitation. Your client side limitation may be smaller.
You can send a wide range of file types, including Microsoft Office® documents (doc, docx, ppt, pptx, xls, xlsx, etc), Openoffice/Libreoffice documents (odt, ods, etc), Adobe® documents (pdf, etc), image file types (jpg, gif, tif, bmp, etc) and more (txt, html, etc).
SMS messages are sent and charged in blocks of characters. One text message is 160 characters. By default, we will limit your message to three-message-parts in length (459 characters using the GSM character set, or 210 characters using Unicode/UCS-2). This can be increased on request. See the SMS Message Parts and Concatenated SMS guide for further information.
Yes, we can provide a daily or monthly email report (as an attached CSV file) containing data on messages sent. This can be used for billing (contains costs) or for reporting (doesn’t contain costs).
Yes, encrypted submissions are accepted across the API via HTTPS. SSL/TLS is also supported for outbound email messages provided the receiving email server supports this.
Some networks support customised SMS Caller IDs. This can be configured using your Web Dashboard.
Your Fax Caller ID can be configured using your Web Dashboard.
Your Voice and TextToSpeech Caller ID is specified on a per-message basis using the 'CallerID' parameter.
");