This API is designed to integrate complex messaging (SMS, Fax and Text-To-Speech) using simple SOAP tools.
This endpoint is preserved for legacy use and is not subject to active feature upgrades.
For access to the most recent features and tools, please refer to our REST API.
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.
Using the API will require a Sender and Token pair to authenticate with the API.
Sender = Sender
APIKey = Token
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:
The possible SOAP response values are:
OK Thanks
Missing sender
Missing token
| 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 | |
| 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 | |
| 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) | |
| 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) | |
| 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) | |
| 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 | ||
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.
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.
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.
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.
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" |
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) |