TNZ API for Messaging

Introduction

TNZ publishes public APIs for developers to utilize TNZ's enhanced messaging tools in their software.

Options include REST, .NET, Python, NodeJS, VBA, SOAP, SMTP and more.

{
    "Sender": "application@domain.com",
    "APIKey": "ta8wr7ymd",
    "MessageData" :
    {
        "Message": "Hello, this is a test message from Department01. Thank you.",
        "Destinations" : 
        [
            { "Recipient": "+6421000002" }
        ]
    }
}      

Sending Messages

The API supports sending a handful of message types, including SMS, Email, Fax, Voice and Voice Text-To-Speech.

API calls may include:

• Authorization/APIKey: Later versions of the APIs utilize an Authorization HTTP Header. You can generate the Authorization token via your dashboard login. Older versions of the APIs use a Sender/APIKey used in the body of the API call. You can set up unlimited APIKeys. You can optionally use a unique one per application. Note: The Sender and APIKey are not validated on initial submission, see TNZ API Errors for details.
• Multiple destinations: Messages can be sent to individual destinations or to multiple destinations at once (as a broadcast)
• MessageID: The MessageID value is used for mapping sent messages with results and replies in webhooks or polls
• Webhook Callback URL: If you have a webhook configured, your API call can specify the URL that webhooks should be delivered to
• SubAccount and Department: If you're sending messages on behalf of customers, these fields are useful for tracking costs and re-billing
• Personalisation: Your API call can include First Names, Company Names, and more. Your messages may include this personalisation (useful when sending broadcasts)
• Sending Time: If you want to load a message now with delayed sending, this is supported.

Webhooks & Polls

You can capture Status and Reply data using webhooks and polls.

The MessageID is useful for matching results.

{
    "Sender": "application@domain.com",
    "APIKey": "ta8wr7ymd",
    "MessageID": "ID123456"
}  

{
    "Result": "Success",
    "Data": {
        "MessageID": "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
        "Status": "Received",
        "JobNum": "10AB20CD",
        "Account": "Account#",
        "SubAccount": "",
        "Department": "",
        "MessageSent": {
            "Date": "2019-12-01 13:45:54",
            "Destination": 6421000001,
            "MessageText": "This is an outbound message sent via API."
        },
        "MessageReceived": [
            {
                "Date": "2019-12-01 14:02:03",
                "From": "+6421000001",
                "MessageText": "This is a reply back from the mobile phone."
            },
            {
                "Date": "2019-12-01 14:04:14",
                "From": "+6421000001",
                "MessageText": "This is a second reply."
            }
        ]
    }
}

Versioning

The API version is specified in the URL you submit calls to.

You can use any version of our API. For example, you may use v1.01 for Email and v2.01 for SMS. This allows for greater flexibility when upgrading components.

The API documentation has a Versioning section which includes a ChangeLog.

Cost Tracking & Rebilling

When submitting API calls, you may include the SubAccount and Department. These are free-format fields.

• Webhooks display the SubAccount and Department used
• The dashboard can be segmented by SubAccount and/or Department, meaning users can only view their own usage reports
• Administrators are able to view usage in the dashboard itemized by SubAccount or Department
• Wholesale CDR reports note the SubAccount and Department for rebilling
• Invoices may be optionally summarised by SubAccount

Number Formatting

When sending SMS, Fax, Voice and TTS, the safest option is to send numbers in internationalised E.164 format, e.g. +642100001 and +61400010001.

Your account can be pre-configured to accept New Zealand and Australian formatting. This means you can submit NZ and AU numbers as a mixture of:
+642100001 and +61400010001
00642100001 and 0061400010001
642100001 and 61400010001
02100001 and 0400010001
2100001 and 400010001

The API is able to accept and strip any unnecessary characters, such as dashes and brackets.