The TPG Telecom Messaging Hub API provides a number of endpoints for building powerful two-way messaging applications. The API provides access to three main resources:

• Messages - Messages delivered from an application to a recipient.
• Delivery Reports - Real time reports on the delivery status of a message. As a message is processed, it's status may change several times before it is finally delivered to a receipient.
• Replies - Messages sent from a recipient to an application. These messages are typically a reply to a previously sent message.

Base URI

The API uses the following base URI:

https://api.messaging.tpgtelecom.com.au

Note: The use of the HTTPS protocol is required.

Authentication

All requests to the TPG API must be authenticated, this can either be done using Basic Authentication or by signing with a HMAC signature.

Credentials

To access the API, an API key and secret are required. These can be generated within the TPG Telecom Messaging Hub portal under API Settings.

Basic Authentication

Every request requires an Authorization header in the following format:

Authorization: Basic Base64(api_key:api_secret)

Where the header consists of the Basic keyword followed by your Basic Authentication api_key and api_secret that you have been supplied by support, seperated with a colon (:) which is then Base64 encoded.

Example request with Basic Authentication

POST /v1/messages HTTP/1.1
Host: api.messaging.tpgtelecom.com.au
Accept: application/json
Content-Type: application/json
Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp
{
  "messages": [
    {
      "content": "Hello World",
      "destination_number": "+61410123456",
      "format": "SMS"
    }
  ]
}

Note: spaces are used as indentation in the body of the above request.

HMAC Authentication

Every request requires an Authorization header in the following formats:

For a request with a request body:

Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="Date Content-MD5 request-line", signature="<SIGNATURE>"

For a request without a request body:

Authorization: hmac username="<API KEY>", algorithm="hmac-sha1", headers="Date request-line", signature="<SIGNATURE>"

To create this header

Step 1

Add a Date header to the request using the current date time in RFC7231 Section 7.1.1.2 format

Step 2

If the request has a body, add a header called Content-MD5 where the value of this header is an MD5 hash of the request body, otherwise this header is not required

Step 3

Create a signing string by concatenating the Date header, the Content-MD5 header (if set) and the request line with line breaks:

Date: Sat, 30 Jul 2022 05:13:23 GMT\nContent-MD5: 10fd4feab20d38432480c07301e49616\nPOST /v1/messages HTTP/1.1

or

Date: Sat, 30 Jul 2022 05:13:23 GMT\nGET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1

Step 4

Create a SHA1 HMAC hash using the signing string and the secret key (both converted to bytes using UTF-8) HMAC-SHA1(signing string, secret)

Step 5

Base64 encode the HMAC hash and include it as the signature in the Authorization header

Example request with body

POST /v1/messages HTTP/1.1
Host: api.messaging.tpgtelecom.com.au
Accept: application/json
Content-Type: application/json
Date: Sat, 30 Jul 2022 05:18:52 GMT
Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="Date Content-MD5 request-line", signature="Ia4G5lkhH/3NDYpix+8ZHUnp6bA="
Content-MD5: 5407644fa83bec240dede971307e0cad
Content-Length: 133
{
  "messages": [
    {
      "content": "Hello World",
      "destination_number": "+61410123456",
      "format": "SMS"
    }
  ]
}

Note: spaces are used as indentation in the body of the above request.

Example request without body

GET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1
Host: api.messaging.tpgtelecom.com.au
Accept: application/json
Date: Sat, 30 Jul 2022 05:18:52 GMT
Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha1", headers="Date request-line", signature="NTUwMjUwNTVmZGYzZTIxODMyYjc1ZmM3M2EwZWQ1NzA3NzA4ZTZjNw=="

Features

De-Duplication

De-Duplication helps you avoid having to undertake data cleansing before commencing send outs. It automatically detects and withholds messages deemed to be duplicates through the use of a 24-hour window – if a message is sent to the same number with the same content within a 24hr period, the subsequent message(s) will be withheld and rejected. To enable this, you don't need to make any changes to your application, just an account configuration change by TPG Telecom Messaging Hub's support team.

Social Sending

Social Sending permits messages to be sent only during sociable hours - i.e. 8am to 6pm (based on your accounts local time zone - not local time). Messages sent outside of these hours are scheduled to be released during the next social time period. This feature helps businesses avoid send-outs during a time that would be deemed unsuitable by the customer. To enable this, you don't need to make any changes to your application, just an account configuration change by TPG Telecom Messaging Hub's support team.

Familiar Sender

Familiar Sender ensures all communication sent to a customer are from the same phone number. This allows businesses to build trust and familiarity with their customers and not confuse them by changing outgoing numbers. To enable this, you don't need to make any changes to your application, just an account configuration change by TPG Telecom Messaging Hub's support team.

Character Converter

Characters in a message may not always fall within the GSM-7 supported character set, and when this occurs all outbound messages will be encoded using UCS-2 leading to the customer being double-charged for the SMS. Character Converter can help you avoid being double-charged for your SMS by converting all characters into the GSM-7 format ensuring you always get the maximum characters into an SMS. Bear in my mind, this will downgrade all your Unicode characters so for instance, your emojis will be translated into a string of unknown characters (eg: �). To enable this, you don't need to make any changes to your application, just an account configuration change by TPG Telecom Messaging Hub's support team.

Contents

• Messages
  • Send messages
  • Get message status
  • Cancel scheduled message
• Source Address
  • Request a Sender Address
  • Submitting a verification code
  • Re-verify Sender Address
  • Get status of a sender address request
  • Get all approved sender addresses
  • Get sender address by id
  • Update My Own Number Label
  • Delete Sender Address
• Delivery Reports
  • Check delivery reports
  • Confirm delivery reports as received
• Messaging Reports
  • Metadata Keys
  • Post detail report
  • Post summary report
  • Post insights report
  • Post async detail report
  • Post async summary report
  • Get async detail report status
  • Get async detail fields
  • Create a scheduled detail report
  • Update a scheduled detail report
  • Create a scheduled summary report
  • Update a scheduled summary report
  • GET active reports
  • Get scheduled report by Id
  • Delete a scheduled report
• Replies
  • Check replies
  • Confirm replies as received
• Webhooks
  • Create Webhook
  • Retrieve Webhook
  • Update Webhook
  • Delete Webhook

Messages

Messages operations.

Send messages

POST /v1/messages

Submit one or more (up to 100 per request) SMS messages for delivery.

The most basic message has the following structure:

{
    "messages": [
        {
            "content": "My first message!",
            "destination_number": "+61410123456"
        }
    ]
}

More advanced delivery features can be specified by setting the following properties in a message:

• callback_url A URL can be included with each message to which Webhooks will be pushed to via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as it is processed (if the delivery report property of the request is set to true) and when replies are received. Specifying a callback URL is optional.
• content The content of the message. This can be a Unicode string, up to 5,000 characters long. Message content is required.
• delivery_report Delivery reports can be requested with each message. If delivery reports are requested, a webhook will be submitted to the callback_url property specified for the message (or to the webhooks specified for the account) every time the status of the message changes as it is processed. Delivery reports are optional and by default will not be requested.
• destination_number The destination number the message should be delivered to. This should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. A destination number is required.
• format The format specifies which format the message will be sent as, SMS (text message), MMS (multimedia message) or TTS (text to speech). With TTS format, we will call the destination number and read out the message using a computer generated voice. Specifying a format is optional, by default SMS will be used.
• media The media is used to specify a list of URLs of the media file(s) that you are trying to send. Supported file formats include png, jpeg and gif. format parameter must be set to MMS for this to work.
• subject The subject field is used to denote subject of the MMS message and has a maximum size of 64 characters long. Specifying a subject is optional.
• source_number_type If a source number is specified, the type of source number may also be specified. This is recommended when using a source address type that is not an internationally formatted number, available options are INTERNATIONAL or ALPHANUMERIC. Specifying a source number type is only valid when the source_number parameter is specified and is optional. If a source number is specified and no source number type is specified, the source number type will be inferred from the source number, however this may be inaccurate.
• source_number[optional] Specify a source number to be used. Refer to the section below for more information on source numbers. ⚠️ The number or sender ID must be registered to your account (from 1-Mar-2024).

Source number (sender ID)

There are several options for the number or sender ID that will show as the source of an outbound message. Some things to note: • If you do not specify a source number, the message will be sent with the default number for your account.

• The default may be a number you have purchased from us - such as a dedicated number, a 10-digit longcode or toll-free number (US/CA), or a shortcode. Log into the web portal to manage your numbers.
• If your account has multiple numbers, you can specify which source number to use in the request.
• If your account does not have a number, your message may be sent using our shared number pool (in certain countries only)

• Alpha tag: In some countries (AU, GB, some others), you may be able to send using an alpha tag - text that represents your brand of business. Before using an alpha tag, you must register it in the Numbers section of the web portal. • Other numbers: You may use numbers that you own as the source number, but you must register them in the Numbers section of the web portal to confirm you have a right to use the number. If you need to register a large number of source numbers/sender IDs, consider using our Source Address API ⚠️ If you specify a source_number that is not registered to your account, the message may fail to send, or may be sent with an alternative number.

• scheduled A message can be scheduled for delivery in the future by setting the scheduled property. The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately.
• message_expiry_timestamp A message expiry timestamp can be provided to specify the latest time at which the message should be delivered. If the message cannot be delivered before the specified message expiry timestamp elapses, the message will be discarded. Specifying a message expiry timestamp is optional.
• metadata Metadata can be included with the message which will then be included with any delivery reports or replies matched to the message. This can be used to create powerful two-way messaging applications without having to store persistent data in the application. Up to 10 key / value metadata data pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to 256 characters long. Specifying metadata for a message is optional.

The response body of a successful POST request to the messages endpoint will include a messages property which contains a list of all messages submitted. The list of messages submitted will reflect the list of messages included in the request, but each message will also contain two new properties, message_id and status. The returned message ID will be a 36 character UUID which can be used to check the status of the message via the Get Message Status endpoint. The status of the message which reflect the status of the message at submission time which will always be

statues.

*Note: when sending multiple messages in a request, all messages must be valid for the request to be successful.
If any messages in the request are invalid, no messages will be sent.*

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
Accept	header	string	No	e.g. application/json

Request body

Optional.

Fields

Field	Type	Required	Description
messages	array of object	Yes
messages[].callback_url	string	No	URL replies and delivery reports to this message will be pushed to
messages[].content	string	No	Content of the message
messages[].destination_number	string	No	Destination number of the message
messages[].delivery_report	boolean	No	Request a delivery report for this message
messages[].format	array of enum: SMS	No	Format of message.
messages[].message_expiry_timestamp	string	No	Date time after which the message expires and will not be sent
messages[].metadata	object	No	Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long `` { "myKey": "myValue", "anotherKey": "anotherValue" } ``
messages[].scheduled	string	No	Scheduled delivery date time of the message
messages[].source_number	string	No
messages[].source_number_type	enum: INTERNATIONAL, ALPHANUMERIC	No	Type of source address specified, this can be INTERNATIONAL or ALPHANUMERIC
messages[].message_id	string	No	Unique ID of the original message
messages[].status	enum: enroute, submitted, delivered, expired, rejected, undeliverable, queued, processed, cancelled, scheduled, failed	No	The status of the message

Example

{
  "messages": [
    {
      "callback_url": "https://my.callback.url.com",
      "content": "My first message",
      "destination_number": "+61410123456",
      "delivery_report": true,
      "format": "SMS",
      "message_expiry_timestamp": "2022-11-03T11:49:02.807Z",
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      },
      "scheduled": "2022-11-03T11:49:02.807Z",
      "source_number": "+61450654321",
      "source_number_type": "INTERNATIONAL"
    },
    {
      "callback_url": "https://my.callback.url.com",
      "content": "My second message",
      "destination_number": "+61410123456",
      "delivery_report": true,
      "format": "SMS",
      "message_expiry_timestamp": "2022-11-03T11:49:02.807Z",
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      },
      "scheduled": "2022-11-03T11:49:02.807Z",
      "source_number": "+61450654321",
      "source_number_type": "INTERNATIONAL"
    }
  ]
}

Responses

202 — Messages were accepted for processing

Field	Type	Required	Description
messages	array of object	No
messages[].message_id	string	No
messages[].callback_url	string	No
messages[].status	string	No
messages[].content	string	No
messages[].destination_number	string	No
messages[].delivery_report	boolean	No
messages[].format	string	No
messages[].message_expiry_timestamp	string	No
messages[].metadata	object	No
messages[].metadata.myKey	string	No
messages[].metadata.anotherKey	string	No
messages[].scheduled	string	No
messages[].source_number	string	No
messages[].source_number_type	string	No

Example:

{
  "messages": [
    {
      "message_id": "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a",
      "callback_url": "https://my.url.com",
      "status": "delivered",
      "content": "My first message",
      "destination_number": "+61410123456",
      "delivery_report": true,
      "format": "SMS",
      "message_expiry_timestamp": "2022-11-03T11:49:02.807Z",
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      },
      "scheduled": "2022-11-03T11:49:02.807Z",
      "source_number": "+61450654321",
      "source_number_type": "INTERNATIONAL"
    }
  ]
}

400 — Request was invalid

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again."
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/messages" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"callback_url":"https://my.callback.url.com","content":"My first message","destination_number":"+61410123456","delivery_report":true,"format":"SMS","message_expiry_timestamp":"2022-11-03T11:49:02.807Z","metadata":{"myKey":"myValue","anotherKey":"anotherValue"},"scheduled":"2022-11-03T11:49:02.807Z","source_number":"+61450654321","source_number_type":"INTERNATIONAL"},{"callback_url":"https://my.callback.url.com","content":"My second message","destination_number":"+61410123456","delivery_report":true,"format":"SMS","message_expiry_timestamp":"2022-11-03T11:49:02.807Z","metadata":{"myKey":"myValue","anotherKey":"anotherValue"},"scheduled":"2022-11-03T11:49:02.807Z","source_number":"+61450654321","source_number_type":"INTERNATIONAL"}]}'

Get message status

GET /v1/messages/{messageId}

Retrieve the current status of a message using the message ID returned in the send messages end point.

A successful request to the get message status endpoint will return a response body as follows:

{
    "format": "SMS",
    "content": "My first message!",
    "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
    },
    "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
    "callback_url": "https://my.callback.url.com",
    "delivery_report": true,
    "destination_number": "+61410123456",
    "scheduled": "2022-11-03T11:49:02.807Z",
    "source_number": "+61450654321",
    "source_number_type": "INTERNATIONAL",
    "message_expiry_timestamp": "2022-11-03T11:49:02.807Z",
    "status": "enroute"
}

The status property of the response indicates the current status of the message. See the Webhooks section of this documentation for more information on message statues. The expiry date for getting an entity is 45 days.

Note: If an invalid or non existent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
messageId	path	string	Yes
Accept	header	string	No	e.g. application/json

Responses

200 — The submitted message including the status of the message

Field	Type	Required	Description
callback_url	string	No	URL replies and delivery reports to this message will be pushed to
content	string	No	Content of the message
destination_number	string	No	Destination number of the message
delivery_report	boolean	No	Request a delivery report for this message
format	enum: SMS	No	Format of message.
message_expiry_timestamp	string	No	Date time after which the message expires and will not be sent
metadata	object	No	Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long `` { "myKey": "myValue", "anotherKey": "anotherValue" } ``
scheduled	string	No	Scheduled delivery date time of the message
source_number	string	No
source_number_type	enum: INTERNATIONAL, ALPHANUMERIC	No	Type of source address specified, this can be INTERNATIONAL or ALPHANUMERIC
message_id	string	No	Unique ID of this message
status	enum: enroute, submitted, delivered, expired, rejected, undeliverable, queued, processed, cancelled, scheduled, failed	No	The status of the message

Example:

{
  "callback_url": "https://my.url.com",
  "content": "Hello world!",
  "destination_number": "+61410123456",
  "delivery_report": true,
  "format": "SMS",
  "message_expiry_timestamp": "2022-11-03T11:49:02.807Z",
  "metadata": {},
  "scheduled": "2022-11-03T11:49:02.807Z",
  "source_number": "+61450654321",
  "source_number_type": "INTERNATIONAL",
  "message_id": "string",
  "status": "delivered"
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Resource not found"
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/messages/{messageId}" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Cancel scheduled message

PUT /v1/messages/{messageId}

Cancel a scheduled message that has not yet been delivered.

A scheduled message can be cancelled by updating the status of a message from scheduled to cancelled. This is done by submitting a PUT request to the messages endpoint using the message ID as a parameter (the same endpoint used above to retrieve the status of a message).

The body of the request simply needs to contain a status property with the value set to cancelled. The expiry date for getting an entity is 45 days.

{
    "status": "cancelled"
}

Note: Only messages with a status of scheduled can be cancelled. If an invalid or non existent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
messageId	path	string	Yes
Accept	header	string	No	e.g. application/json

Request body

Optional.

Fields

Field	Type	Required	Description
status	enum: cancelled	Yes	Must be set to cancelled.

Example

{
  "status": "cancelled"
}

Responses

200 — Message status updated successfully

400 — Bad request

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Message is not currently scheduled"
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Resource not found"
}

Example request

curl -X PUT "https://api.messaging.tpgtelecom.com.au/v1/messages/{messageId}" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"status":"cancelled"}'

Source Address

The source address API provides several endpoints for you to request an SMS sender ID and track its approval status.

What is Trusted Sender ID?

Simply put, a sender ID is whatever you send a text message from. This is typically either a phone number, or a string of alphanumeric characters (commonly referred to as an “Alpha Tag”).

With regulations surrounding SMS becoming much stricter all over the world in an effect to combat scam SMS messages, TPG Telecom is working on “Trusted Sender ID” a concept that allows customers to request a Sender ID and have it verified.

Currently, Trusted Sender ID supports two types of Sender ID: Alpha Tags and Personal (“Own”) Numbers. It will likely be extended to support additional number types, such as TFN and 10DLC where additional registration, (external) verification, and overall account whitelist of numbers will be required.

Alpha Tag

Sending messages from your brand name is particularly ideal for SMS marketing and two-factor authentication, as it increases recognition and trust. There are, however, a few considerations to be aware of.

Alpha tags are made up of 3-11 letters and/or numbers. Alpha tags must be registered and approved before sending and must have clear relevancy to your business and/or use case.

Alpha Tags appear as the “From” number when you receive messages.

A good alpha tag meets at least one of the following valid use cases:

• Business names
• Trademark names
• Product or service name
• an acronym, initialism, or contraction of your entity

In addition to the requirements around clearly relating to the business, we typically advise the following for alpha tags to ensure maximum compatibility with the various carriers:

• 6-11 characters long
• Only contains characters from the following sets:
• A-Z
• a-z
• 0-9
• _ (underscore)
• \- (hyphen)

Alpha Tags can currently be registered through the Source Address API for the following countries: AU and GB

To register an Alpha Tag as a sender ID you must:

1. Make a request to the Request a Sender Address endpoint
2. Wait for the alpha tag to be approved. The status of the alpha tag can be monitored using the Get status of a sender address request endpoint

Once the alpha tag has been approved, you can begin using it as a Sender ID for SMS messages.

Personal Number

A personal number, or “My Own Number”, is a number that you own rather than one provided to you by TPG Telecom. Typically, this is your personal mobile phone number. You may wish to register this number for use with our service so that you can easily send messages from a number already associated with your organisation.

Before you can send messages using your own number, you need to verify that you have a right to use that number. Ensuring you have a right to use a phone number is an important regulatory requirement, aiming to prevent scam, spam, and misuse of messaging services.

Personal numbers can currently be registered through the Source Address API for the following countries: AT, AU, CH, CY, DE, DK, EE, ES, FI, GB, HR, IE, IT, LT, LU, LV, MT, NL, NO, PT, SE, and SI

To register a personal number as a Sender ID you must:

1. Make a request to the Request a Sender Address endpoint
2. A unique verification code will be sent to the requested number
3. Make a request to the Submitting a Verification Code endpoint, using the verification code that was sent in the previous step. A 200 OK response will indicate the number has been verified and is ready for use.

⚠️ Own numbers need to be re-verified every 12 months. You will be notified by email that verification of your number is about to expire.

Requesting a Source Address on behalf of a sub-account

By default, all requests made through the API are made on behalf of the account that the API keys used to authorize the request were made on. API keys created on a parent account can request a source address on behalf of a sub-account. To do this, include a header key Account with the sub-account ID as the value. For example: Account: mySubAccount

Example request with Request a Sender Address from a sub-account

POST /v1/messaging/numbers/sender_address/requests HTTP/1.1
Host: api.messagemedia.com
Accept: application/json
Content-Type: application/json
Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp
Account: mySubAccount
{
  "sender_address": "+61341234131",
  "sender_address_type": "INTERNATIONAL",
  "usage_type": "OWN_NUMBER",
  "destination_countries": [
      "AU"
  ],
  "reason": "I confirm that my business has a valid use case",
  "label": "my number sample"
}

Note: The use of the Account header key applies to all Source Address endpoints.

Request a Sender Address

POST /v1/messaging/numbers/sender_address/requests

Submit a request to register a new Sender ID. When making a request to this endpoint, you will always need to specify sender_address_type and usage_type parameters. The following table shows the acceptable values and combinations for these parameters:

Sender ID	sender_address_type	usage_type
Alpha tag	ALPHANUMERIC	ALPHANUMERIC
Personal number	INTERNATIONAL	OWN_NUMBER

The other parameters required for your request will depend on the type of Sender ID you are registering.

Sender ID is an Alpha Tag

The following parameters are used when registering an alpha tag as a Sender ID:

• sender_address: (Required). The alphanumeric string that you wish register as an alpha tag. This parameter is case insensitive. If this alpha tag already exists on your account, you will receive a conflict error message.
• destination_countries: (Required). The countries that you wish to register the alpha tag for use in, in two-character ISO 3166 format. Currently AU and GB are supported.
• sender_address_type: (Required). For alpha tags this is always ALPHANUMERIC
• usage_type: (Required). For alpha tags this is always ALPHANUMERIC
• label: (Optional). A reference name for the sender ID to allow you to easily track it.
• reason: (Required). This is a specifically formatted string made up of the following sub-items (all of which are required):
• useCase: one of the following:
  • SOLE_TRADER_NAME
  • COMPANY_NAME
  • PARTNERSHIP_NAME
  • REGISTERED_TRUST_NAME
  • CO_OPERATIVE_NAME
  • INDIGENOUS_CORPORATION_NAME
  • REGISTERED_ORGANISATION_NAME
  • PERSONAL_NAME
  • AUSTRALIAN_TRADEMARK
  • INTERNATIONAL_TRADEMARK
  • AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY
  • FOREIGN_GOVERNMENT_AGENCY_OR_ENTITY
  • PRODUCT_OR_SERVICE_NAME
  • ACRONYM_INITIALISM
  • CONTRACTION_OF_NAME
  • OTHER
• description: A description used if OTHER was selected as the use case. Limited to 200 characters.
• email: The preferred contact email for our approval team when additional details are required.
• australianGovernmentAgencyOrEntityName: The name of your organisation.
• abn: Your organisation’s Australian Business Number
• statement: A legal declaration
  • If applying for your own business: “We are authorized to use the Sender ID with a valid use case.”
  • If applying on behalf of a third-party entity: “We are authorized to use the Sender ID on behalf of [full entity name of sender] with a valid use case.”

The reason parameter must contain all the above items. A well formatted reason looks like the following:

{
  "reason": {
    "useCase": "AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY",
    "description": "bal bla",
    "email": "example@email.com",
    "australianGovernmentAgencyOrEntityName": "bla bla",
    "statement": "We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case."
  }
}

Sender ID is a Personal Number

The following parameters are used when registering a personal mobile phone number as a Sender ID:

• sender_address: (Required). The phone number that you wish register as a personal number. This number must be in E.164. If this number is already registered to an account, you will receive a conflict error message.
• destination_countries: (Required). The country of the number that you wish to register, in two-character ISO 3166 format. Refer to the Types of Sender ID section for a list of currently supported countries.
• sender_address_type: (Required). For personal numbers this is always INTERNATIONAL
• usage_type: (Required). For personal numbers this is always OWN_NUMBER
• label: (Optional). A reference name for the sender ID to allow you to easily track it.
• Reason: (Required). A string describing why you wish to register the number as a Sender ID. Limited to 200 characters.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Example

{
  "sender_address": "EXAMPLE",
  "sender_address_type": "ALPHANUMERIC",
  "usage_type": "ALPHANUMERIC",
  "destination_countries": [
    "AU"
  ],
  "reason": {
    "useCase": "AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY",
    "description": "bal bla",
    "email": "example@email.com",
    "australianGovernmentAgencyOrEntityName": "bla bla",
    "statement": "We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case."
  },
  "label": "label"
}

Responses

201 — + Verification Code Request

Field	Type	Required	Description
id	string	Yes	The ID of the request.
sender_address	string	Yes	The phone number to register as a personal number.
sender_address_type	string	Yes	Always INTERNATIONAL for personal numbers.
usage_type	string	Yes	Always OWN_NUMBER for personal numbers.
destination_countries	array of string	Yes	Countries to register the personal number for use in.
reason	string	Yes	A string describing why you wish to register the number as a Sender ID.
label	string	No	A reference name for the sender ID (optional).
status	string	Yes	The status of the request.
account_id	string	Yes	The account ID.
created_date	string	Yes	The date the request was created.
last_modified_date	string	Yes	The date the request was last modified.

Example:

{
  "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b8",
  "sender_address": "+61401234567",
  "sender_address_type": "INTERNATIONAL",
  "usage_type": "OWN_NUMBER",
  "destination_countries": [
    "AU"
  ],
  "reason": "my personal number",
  "label": "label",
  "status": "PENDING",
  "account_id": "XYZ_ExampleAccount",
  "created_date": "2023-10-24T14:15:22Z",
  "last_modified_date": "2023-10-24T14:15:22Z"
}

400 — Bad Request

401 — Unauthorised

403 — Forbidden

409 — Conflict

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/requests" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"sender_address":"EXAMPLE","sender_address_type":"ALPHANUMERIC","usage_type":"ALPHANUMERIC","destination_countries":["AU"],"reason":{"useCase":"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY","description":"bal bla","email":"example@email.com","australianGovernmentAgencyOrEntityName":"bla bla","statement":"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case."},"label":"label"}'

Submitting a verification code

POST /v1/messaging/numbers/sender_address/requests/{id}/verify

Complete the 2FA verification process required to register a Personal Number as a Sender ID.

• id: The UUID received in the API response of your request to the Request a Sender Address endpoint.
• verification_code: The six-digit code received via SMS to the phone number that you are attempting to register

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	The UUID received in the API response of your request to the Request a Sender Address endpoint.

Request body

Optional.

Example

{
  "verification_code": "123456"
}

Responses

201 — Created

Field	Type	Required	Description
id	string	Yes	The ID of the request.
sender_address	string	Yes	The phone number to register as a personal number.
sender_address_type	string	Yes	Always INTERNATIONAL for personal numbers.
usage_type	string	Yes	Always OWN_NUMBER for personal numbers.
destination_countries	array of string	Yes	Countries to register the personal number for use in.
reason	string	Yes	A string describing why you wish to register the number as a Sender ID.
label	string	No	A reference name for the sender ID (optional).
status	string	Yes	The status of the request.
account_id	string	Yes	The account ID.
created_date	string	Yes	The date the request was created.
last_modified_date	string	Yes	The date the request was last modified.

Example:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "verified",
  "verification_code": "123456"
}

400 — Bad Request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Resource not found"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/requests/123e4567-e89b-12d3-a456-426614174000/verify" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"verification_code":"123456"}'

Re-verify Sender Address

POST /v1/messaging/numbers/sender_address/addresses/{id}/reverify

The below table defines the allowed combination of sender_address_type and usage_type values:

Description	sender_address_type	usage_type
Own Number	INTERNATIONAL	OWN_NUMBER

OWN_NUMBER Sender Addresses require reverification every 12 months to allow continued use. The reverification process is quite similar to the original verification process for the Sender Address, and requires a fresh 2FA check.

To reverify an OWN_NUMBER Sender Address:

1. Retrieve the UUID for the OWN_NUMBER using the Get all approved sender addresses endpoint
2. Make a request to this endpoint to trigger the 2FA check
3. Make a PATCH request to the Submit verification code endpoint, providing the new 2FA code in the body of the request

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Sender Address ID

Responses

200 — OK

Field	Type	Required	Description
id	string	No	Primary ID of the record
sender_address	string	No	The Sender Address to be requested
sender_address_type	enum: INTERNATIONAL	No	The Sender Address Type
usage_type	enum: OWN_NUMBER	No	The Sender Address Usage Type
destination_countries	array of string	No	List of 2-character ISO country codes this sender address applies to
reason	string	No
label	string	No
status	enum: PENDING	No
account_id	string	No
created_date	string	No
last_modified_date	string	No

Example:

{
  "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b7",
  "sender_address": "+61450999999",
  "sender_address_type": "INTERNATIONAL",
  "usage_type": "OWN_NUMBER",
  "destination_countries": [
    "AU",
    "NZ",
    "US"
  ],
  "reason": "my company is example.com",
  "label": "Example Address",
  "status": "PENDING",
  "account_id": "XYZ_ExampleAccount",
  "created_date": "2019-08-24T14:15:22Z",
  "last_modified_date": "2019-08-24T14:15:22Z"
}

400 — Bad request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Resource not found."
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/addresses/123e4567-e89b-12d3-a456-426614174000/reverify" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Get status of a sender address request

GET /v1/messaging/numbers/sender_address/requests/{id}

Retrieve the current status of a sender address request using the request ID returned in the sender address request endpoint.

A successful request to the get message status endpoint will return a response body as follows:

{
    "id": "365dd65f-7101-46cd-8e79-e49c5620eb15",
    "sender_address": "sample",
    "sender_address_type": "ALPHANUMERIC",
    "usage_type": "ALPHANUMERIC",
    "destination_countries": [
        "AU"
    ],
    "reason": "This is my approval reason",
    "label": "label",
    "status": "APPROVED",
    "account_id": "sample",
    "created_date": "2023-09-07T05:48:26.741Z",
    "last_modified_date": "2023-09-07T05:49:20.888Z"
}

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	36 character UUID.

Responses

200 — OK

Field	Type	Required	Description
id	string	No	Primary ID of the record
sender_address	string	No	The Sender Address to be requested
sender_address_type	enum: ALPHANUMERIC	No	The Sender Address Type
usage_type	enum: ALPHANUMERIC	No	The Sender Address Usage Type
destination_countries	array of string	No	List of 2-character ISO country codes this sender address applies to
reason	string	No
label	string	No
status	enum: OPEN, PENDING, REJECTED, APPROVED	No
account_id	string	No
created_date	string	No
last_modified_date	string	No

Example:

{
  "id": "365dd65f-7101-46cd-8e79-e49c5620eb15",
  "sender_address": "sample",
  "sender_address_type": "ALPHANUMERIC",
  "usage_type": "ALPHANUMERIC",
  "destination_countries": [
    "AU"
  ],
  "reason": "This is my approval reason",
  "label": "label",
  "status": "OPEN",
  "account_id": "sample",
  "created_date": "2023-09-07T05:48:26.741Z",
  "last_modified_date": "2023-09-07T05:49:20.888Z"
}

400 — Bad request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Resource not found."
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/requests/365dd65f-7101-46cd-8e79-e49c5620eb15" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Get all approved sender addresses

GET /v1/messaging/numbers/sender_address/addresses

Retrieve all sender addresses currently registered to your account.

Authentication: basic_auth or hmac_auth

Request body

Request body as present in the Apiary dump (unusual for GET).

Optional.

Fields

Field	Type	Required	Description
(body)	string	No

Example

string

Responses

200 — OK

Field	Type	Required	Description
data	array of object	No
data[].id	string	Yes
data[].sender_address	string	Yes
data[].sender_address_type	string	Yes
data[].usage_type	string	Yes
data[].destination_countries	array of string	Yes
data[].reason	string	Yes
data[].label	string	Yes
data[].account_id	string	Yes
data[].created_date	string	Yes
data[].last_modified_date	string	Yes
data[].expiry	string	No
data[].display_status	string	No
pagination	object	No
pagination.page_size	number	No
pagination.next_token	string	No

Example:

{
  "data": [
    {
      "id": "7927d9eb-4e74-4021-836e-6cae071f84e7",
      "sender_address": "EXAMPLE1",
      "sender_address_type": "ALPHANUMERIC",
      "usage_type": "ALPHANUMERIC",
      "destination_countries": [
        "AU"
      ],
      "reason": "This is my reason 1",
      "label": "This is my label 1",
      "account_id": "my_account",
      "created_date": "2023-08-04T04:21:55.958Z",
      "last_modified_date": "2023-08-04T04:21:55.958Z"
    },
    {
      "id": "365dd65f-7101-46cd-8e79-e49c5620eb15",
      "sender_address": "EXAMPLE2",
      "sender_address_type": "ALPHANUMERIC",
      "usage_type": "ALPHANUMERIC",
      "destination_countries": [
        "AU"
      ],
      "reason": "This is my reason 2",
      "label": "This is my label 2",
      "account_id": "my_account",
      "created_date": "2023-08-14T04:21:55.958Z",
      "last_modified_date": "2023-08-14T04:21:55.958Z"
    },
    {
      "id": "4a9cb0f4-f383-40b5-84dc-bbb6a3b210dd",
      "sender_address": "61491570156",
      "sender_address_type": "INTERNATIONAL",
      "usage_type": "OWN_NUMBER",
      "destination_countries": [
        "AU"
      ],
      "reason": "This is my reason 3",
      "label": "This is my label 3",
      "account_id": "my_account",
      "created_date": "2023-08-24T04:21:55.958Z",
      "last_modified_date": "2023-08-24T04:21:55.958Z",
      "expiry": "2024-08-03T04:21:55.958Z",
      "display_status": "APPROVED"
    }
  ],
  "pagination": {
    "page_size": 20,
    "next_token": "UWFTeXNBZGRyMSN8JEAsdmVuZG9ySWRUZXN0MSN8JEAsYWNjb3VudElkVGVzdDI="
  }
}

400 — Bad request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Resource not found."
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/addresses" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '"string"'

Get sender address by id

GET /v1/messaging/numbers/sender_address/addresses/{id}

Retrieve a sender address currently registered to your account by Id.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	The UUID of the sender address.

Responses

200 — OK

Field	Type	Required	Description
id	string	Yes	Primary ID of the record
sender_address	string	Yes	The Own Number to be requested
sender_address_type	enum: INTERNATIONAL	Yes	The Sender Address Type
usage_type	enum: OWN_NUMBER	Yes	The Sender Address Usage Type
destination_countries	array of string	Yes	List of 2-character ISO country codes this sender address applies to
reason	string	No	The reason associated with the Sender Address
label	string	No	The label associated with the Sender Address
account_id	string	Yes	The ID of the account associated with the Sender Address
created_date	string	Yes	The date and time when the Sender Address was created
last_modified_date	string	Yes	The date and time when the Sender Address was last modified
expiry	string	No	The Sender Address expiration time (applies for sender_address_type = OWN_NUMBER)
display_status	enum: APPROVED, EXPIRED, EXPIRING	No	The current display status of the Sender Address

Example:

{
  "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b8",
  "sender_address": "+61401234567",
  "sender_address_type": "INTERNATIONAL",
  "usage_type": "OWN_NUMBER",
  "destination_countries": [
    "AU"
  ],
  "reason": "my personal number",
  "label": "ABC",
  "account_id": "XYZ_ExampleAccount",
  "created_date": "2019-08-24T14:15:22Z",
  "last_modified_date": "2019-08-24T14:15:22Z",
  "expiry": "2019-08-24T14:15:22Z",
  "display_status": "APPROVED"
}

400 — Bad request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/addresses/01ccaccb-e654-4503-bb7e-XXXXXXXXXXXX" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Update My Own Number Label

PATCH /v1/messaging/numbers/sender_address/addresses/{id}

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	The UUID of the sender address.

Request body

Optional.

Example

{
  "label": "string"
}

Responses

200 — OK

Field	Type	Required	Description
id	string	No	Primary ID of the record
sender_address	string	No	The Own Number to be requested
sender_address_type	enum: INTERNATIONAL	No	The Sender Address Type
usage_type	enum: OWN_NUMBER	No	The Sender Address Usage Type
destination_countries	array of string	No	List of 2-character ISO country codes this sender address applies to
reason	string	No	Reason for the sender address
label	string	No	Label associated with the sender address
account_id	string	No	Account ID associated with the sender address
created_date	string	No	Date and time when the sender address was created
last_modified_date	string	No	Date and time when the sender address was last modified
expiry	string	No	The Sender Address expiration time (applies for sender_address_type = OWN_NUMBER)
display_status	enum: APPROVED, EXPIRED, EXPIRING	No	Current display status of the sender address

Example:

{
  "id": "6f79a12e-14f1-4776-adc0-5c5e48a999b8",
  "sender_address": "+61401234567",
  "sender_address_type": "INTERNATIONAL",
  "usage_type": "OWN_NUMBER",
  "destination_countries": [
    "AU"
  ],
  "reason": "my personal number",
  "label": "ABC",
  "account_id": "XYZ_ExampleAccount",
  "created_date": "2019-08-24T14:15:22Z",
  "last_modified_date": "2019-08-24T14:15:22Z",
  "expiry": "2019-08-24T14:15:22Z",
  "display_status": "APPROVED"
}

400 — Bad request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Resource not found."
}

Example request

curl -X PATCH "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/addresses/01ccaccb-e654-4503-bb7e-XXXXXXXXXXXX" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"string"}'

Delete Sender Address

DELETE /v1/messaging/numbers/sender_address/addresses/{id}

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	The UUID of the sender address.

Responses

202 — Accepted

400 — Bad request

Field	Type	Required	Description
message	string	Yes
details	array of string	Yes

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again.",
  "details": [
    "Failed to parse message body."
  ]
}

401 — Unauthorised

403 — Forbidden

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	Yes

Example:

{
  "message": "Resource not found."
}

Example request

curl -X DELETE "https://api.messaging.tpgtelecom.com.au/v1/messaging/numbers/sender_address/addresses/01ccaccb-e654-4503-bb7e-XXXXXXXXXXXX" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Delivery Reports

If a callback URL is specified in the submit message request, then changes to the message status, replies received in response to the message or delivery reports received for the message will be pushed via a HTTP POST request. An alternative to delivery reports via callbacks is custom webhooks using the webhooks management API.

All notifications are JSON encoded and the request expects to receive a response in the HTTP 200 range. If a valid response isn't received the request will be retried in an exponentially backing off fashion.

For delivery reports or changes in the status of a message, the POST request to the specified URL will be as follows:

Note, multiple delivery report notifications will be recieved for a single message.

{
  "callback_url":"http://mockbin.org/bin/ac52ebd4-eca1-4c86-bf38-4dce79633906",
  "delivery_report_id":"693e87f2-a553-4281-9ffe-ddf04cbc4bf3",
  "source_number":"+61491570156",
  "date_received":"2022-11-03T11:49:02.807Z",
  "status":"delivered",
  "delay":0,
  "submitted_date":"2022-11-03T11:49:01.551Z",
  "original_text":"Hello world!",
  "message_id":"389dc1a8-62a4-4110-ba61-af94806c006f",
  "vendor_account_id":{
    "vendor_id":"TPGTelecom",
    "account_id":"MyAccount"
  },
  "error_code":"220",
  "metadata":{
    "key":"value"
  }
}

The properties included in the notification are as follows:

• Callback URL: The URL specified as the callback URL in the original submit message request.
• Delivery Report ID: A unique ID for the delivery report that this notification represents.
• Source Number: The destination address of the original message.
• Date Received: The date and time at which this notification was generated in UTC.
• Status: The status of the message as indicated by this delivery report. The status field can be one of the following values:
  • enroute: Message has been received by the gateway and is being processed (or waiting to be processed).
  • submitted: Message has been submitted to a provider/carrier for delivery.
  • delivered: Message delivery has been confirmed by the provider, including to the handset (where possible).
  • expired: The message has expired.
  • rejected: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered
  • failed: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider.
• Delay: Deprecated, no longer in use
• Submitted Date: Date time status of the message changed in UTC. For a delivered DR this may indicate the time at which the message was received on the handset.
• Original Text: Text of the original message.
• Message ID: ID of the original message.
• Vendor Account ID: The account used to submit the original message. The vendor will always be TPGTelecom
• Metadata: Any metadata that was included in the original submit message request.
• Error Code: A status code which provides additional information about the message status:
  • 101: Message being processed by the gateway.
  • 102: Message is being rerouted to a different provider after failing via the first provider.
  • 151: Message held for screening.
  • 200: Message submitted to downstream provider for delivery.
  • 210: Message accepted by downstream provider.
  • 211: Message is enroute for delivery by provider.
  • 212: Message submitted. Delivery pending.
  • 213: Message scheduled for delivery by downstream provider.
  • 220: Message delivered.
  • 221: Message delivered to the handset.
  • 320: Message validity period has expired (prior to submission).
  • 401: Message validity period has expired (before delivery).
  • 301: Usage threshold reached. Message discarded.
  • 302: Destination address blocked. Message discarded.
  • 303: Source address blocked. Message discarded.
  • 304: Message dropped. Contact support.
  • 305: Message discarded due to duplicate detection.
  • 402: Message rejected by downstream provider.
  • 403: Message skipped by downstream provider.
  • 410: Invalid source address.
  • 411: Invalid destination address.
  • 412: Destination address blocked.
  • 413: SMS service unavailable on destination.
  • 414: Destination unreachable.
  • 330: Gateway failure.
  • 331: Message discarded.
  • 332: No available route to destination.
  • 333: Source address unsupported for this destination.
  • 400: Message failed; undeliverable.
  • 405: Message cancelled or deleted by provider.

Check delivery reports

GET /v1/delivery_reports

Check for any delivery reports that have been received.

Delivery reports are a notification of the change in status of a message as it is being processed.

Each request to the check delivery reports endpoint will return any delivery reports received that have not yet been confirmed using the confirm delivery reports endpoint. A response from the check delivery reports endpoint will have the following structure:

{
    "delivery_reports": [
        {
            "callback_url": "https://my.callback.url.com",
            "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043",
            "source_number": "+61491570157",
            "date_received": "2022-05-20T06:30:37.642Z",
            "status": "enroute",
            "delay": 0,
            "submitted_date": "2022-05-20T06:30:37.639Z",
            "original_text": "My first message!",
            "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba",
            "vendor_account_id": {
                "vendor_id": "TPGTelecom",
                "account_id": "MyAccount"
            },
            "metadata": {
                "myKey": "myValue",
                "anotherKey": "anotherValue"
            }
        },
        {
            "callback_url": "https://my.callback.url.com",
            "delivery_report_id": "0edf9022-7ccc-43e6-acab-480e93e98c1b",
            "source_number": "+61491570158",
            "date_received": "2022-05-21T01:46:42.579Z",
            "status": "enroute",
            "delay": 0,
            "submitted_date": "2022-05-21T01:46:42.574Z",
            "original_text": "My second message!",
            "message_id": "fbb3b3f5-b702-4d8b-ab44-65b2ee39a281",
            "vendor_account_id": {
                "vendor_id": "TPGTelecom",
                "account_id": "MyAccount"
            },
            "metadata": {
                "myKey": "myValue",
                "anotherKey": "anotherValue"
            }
        }
    ]
}

Each delivery report will contain details about the message, including any metadata specified and the new status of the message (as each delivery report indicates a change in status of a message) and the timestamp at which the status changed. Every delivery report will have a unique delivery report ID for use with the confirm delivery reports endpoint.

Note: The source number and destination number properties in a delivery report are the inverse of those specified in the message that the delivery report relates to. The source number of the delivery report is the destination number of the original message.

Subsequent requests to the check delivery reports endpoint will return the same delivery reports and a maximum of 100 delivery reports will be returned in each request. Applications should use the confirm delivery reports endpoint in the following pattern so that delivery reports that have been processed are no longer returned in subsequent check delivery reports requests. The expiry date for getting an entity is 45 days.

1. Call check delivery reports endpoint
2. Process each delivery report
3. Confirm all processed delivery reports using the confirm delivery reports endpoint

Note: It is recommended to use the Webhooks feature to receive delivery reports rather than polling the check delivery reports endpoint.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
Accept	header	string	No	e.g. application/json

Responses

200 — Unconfirmed reports

Field	Type	Required	Description
delivery_reports	array of object	No
delivery_reports[].callback_url	string	Yes
delivery_reports[].delivery_report_id	string	Yes
delivery_reports[].source_number	string	Yes
delivery_reports[].date_received	string	Yes
delivery_reports[].status	string	Yes
delivery_reports[].delay	number	Yes
delivery_reports[].submitted_date	string	Yes
delivery_reports[].original_text	string	Yes
delivery_reports[].message_id	string	Yes
delivery_reports[].vendor_account_id	object	Yes
delivery_reports[].vendor_account_id.vendor_id	string	No
delivery_reports[].vendor_account_id.account_id	string	No
delivery_reports[].metadata	object	Yes
delivery_reports[].metadata.myKey	string	No
delivery_reports[].metadata.anotherKey	string	No

Example:

{
  "delivery_reports": [
    {
      "callback_url": "https://my.callback.url.com",
      "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043",
      "source_number": "+61491570157",
      "date_received": "2022-05-20T06:30:37.642Z",
      "status": "enroute",
      "delay": 0,
      "submitted_date": "2022-05-20T06:30:37.639Z",
      "original_text": "My first message!",
      "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba",
      "vendor_account_id": {
        "vendor_id": "TPGTelecom",
        "account_id": "MyAccount"
      },
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      }
    },
    {
      "callback_url": "https://my.callback.url.com",
      "delivery_report_id": "0edf9022-7ccc-43e6-acab-480e93e98c1b",
      "source_number": "+61491570158",
      "date_received": "2022-05-21T01:46:42.579Z",
      "status": "submitted",
      "delay": 0,
      "submitted_date": "2022-05-21T01:46:42.574Z",
      "original_text": "My second message!",
      "message_id": "fbb3b3f5-b702-4d8b-ab44-65b2ee39a281",
      "vendor_account_id": {
        "vendor_id": "TPGTelecom",
        "account_id": "MyAccount"
      },
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      }
    }
  ]
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Resource not found"
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/delivery_reports" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Confirm delivery reports as received

POST /v1/delivery_reports/confirmed

Mark a delivery report as confirmed so it is no longer return in check delivery reports requests.

The confirm delivery reports endpoint is intended to be used in conjunction with the check delivery reports endpoint to allow for robust processing of delivery reports. Once one or more delivery reports have been processed, they can then be confirmed using the confirm delivery reports endpoint so they are no longer returned in subsequent check delivery reports requests.

The confirm delivery reports endpoint takes a list of delivery report IDs as follows:

{
    "delivery_report_ids": [
        "011dcead-6988-4ad6-a1c7-6b6c68ea628d",
        "3487b3fa-6586-4979-a233-2d1b095c7718",
        "ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
    ]
}

The expiry date for getting an entity is 45 days. Up to 100 delivery reports can be confirmed in a single confirm delivery reports request.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
Accept	header	string	No	e.g. application/json

Request body

Optional.

Example

{
  "delivery_report_ids": [
    "011dcead-6988-4ad6-a1c7-6b6c68ea628d",
    "3487b3fa-6586-4979-a233-2d1b095c7718",
    "ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
  ]
}

Responses

202 — Requested delivery reports will be marked as confirmed

400 — Bad request

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again."
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Resource not found"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/delivery_reports/confirmed" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"delivery_report_ids":["011dcead-6988-4ad6-a1c7-6b6c68ea628d","3487b3fa-6586-4979-a233-2d1b095c7718","ba28e94b-c83d-4759-98e7-ff9c7edb87a1"]}'

Messaging Reports

Messaging Reports operations.

Metadata Keys

POST /v2-preview/reporting/messages/metakeys

Returns a list of metadata keys

• page Page number for paging through paginated result sets.
• page_size Number of results to return in a page for paginated result sets.
• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Responses

200 — OK

Field	Type	Required	Description
keys	array of object	Yes

Example:

{
  "keys": [
    "meta1",
    "meta2",
    "meta3"
  ]
}

400 — Bad Request

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/metakeys" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Post detail report

POST /v2-preview/reporting/messages/detail

Generates a report listing all sent and/or received messages within a specified time period.

• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• timezone The timezone of the messages to include, using the name of the region.
• source Filter results by source address.
• destination Filter results by destination address.
• destinations Filter results by multiple destination addresses. This property overrides the destination parameter.
• metadata_key Filter results for messages that include a metadata key.
• metadata_value Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.
• metadata_values Filter results for messages that include a metadata key containing these values. This parameter overrides the metadata_value property. If this parameter is provided, the metadata_key parameter must also be provided.
• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

• status Items Enum: UNDEFINED QUEUED PROCESSING PROCESSED FAILED SCHEDULED CANCELLED DELIVERED EXPIRED ENROUTE HELD SUBMITTED REJECTED READ

  An array of message statuses

• opt_out Filter the report to only include messages that triggered an opt out
• mms_media Filter results by mms media.

• message_format Items Enum: MMS SMS TTS RCS CHANNEL

  Format of message type.

• page Page number for paging through paginated result sets.
• page_size Number of results to return in a page for paginated result sets.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
start_date	string	Yes	Inclusive (timestamp is greater than or equal)
end_date	string	Yes	Exclusive (timestamp is less than)
direction	enum: all, outbound, inbound	No
timezone	string	No
source	string	No
destination	string	No
destinations	array of object	No	Those values will override the field destination
metadata_key	string	No
metadata_value	string	No
metadata_values	array of object	No	Those values will override metadata-value
accounts	array of object	No
status	array of object	No
opt_out	string	No
mms_media	string	No
message_format	array of object	No
page	number	No
page_size	number	No

Example

{
  "start_date": "2019-12-12T00:00:00.000+11:00",
  "end_date": "2019-12-14T00:00:00.000+11:00",
  "direction": "all",
  "timezone": "Australia/Sydney",
  "source": "+61555555555",
  "destination": "+61555555555",
  "metadata_key": "broadcastId",
  "metadata_value": "ABC",
  "accounts": [
    "Account1",
    "Account2"
  ],
  "status": [
    "UNDEFINED"
  ],
  "opt_out": "true",
  "mms_media": "true",
  "message_format": [
    "SMS"
  ],
  "page": 0,
  "page_size": 20
}

Responses

200 — OK

Field	Type	Required	Description
messages	array of object	No
pagination	object	No
pagination.page	number	No
pagination.page_size	number	No
pagination.has_next	boolean	No

Example:

{
  "messages": [
    {
      "message_id": "",
      "format": "SMS",
      "timestamp": "2019-12-06T08:11:43.020Z",
      "delivered_timestamp": "2019-12-06T08:11:44.020Z",
      "direction": "all",
      "status": "UNDEFINED",
      "status_code": 0,
      "status_description": "\"Unknown\"",
      "source_address": "+6111",
      "source_address_country": "AU",
      "destination_address": "+6000",
      "destination_address_country": "AU",
      "content": "Test",
      "account_id": "global",
      "action": "null",
      "units": 1,
      "metadata": [
        {
          "key": "broadcastId",
          "value": "123"
        }
      ]
    }
  ],
  "pagination": {
    "page": 0,
    "page_size": 20,
    "has_next": false
  }
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/detail" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2019-12-12T00:00:00.000+11:00","end_date":"2019-12-14T00:00:00.000+11:00","direction":"all","timezone":"Australia/Sydney","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","mms_media":"true","message_format":["SMS"],"page":0,"page_size":20}'

Post summary report

POST /v2-preview/reporting/messages/summary

Create daily report summary containing total number of sent, received and billing units.

• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.
• timezone The timezone of the messages to include, using the name of the region.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• source Filter results by source address.
• destination Filter results by destination address.
• metadata_key Filter results for messages that include a metadata key.
• metadata_value Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.
• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

• status Items Enum: UNDEFINED QUEUED PROCESSING PROCESSED FAILED SCHEDULED CANCELLED DELIVERED EXPIRED ENROUTE HELD SUBMITTED REJECTED READ

  An array of message statuses

• opt_out Filter the report to only include messages that triggered an opt out

• group_by Items Enum: ACCOUNT DAY WEEK MONTH YEAR METADATA_KEY METADATA_VALUE STATUS COUNTRY

  Group results by a list of values, from the enumerable table above.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Responses

200 — OK

Field	Type	Required	Description
summaries	array of object	No
total_sent	number	No
total_received	number	No
total_billing_units	number	No
total_optout	number	No

Example:

{
  "summaries": [
    {
      "group": "Account1",
      "total_sent": 0,
      "total_received": 0,
      "total_billing_units": 0,
      "total_optout": 0,
      "sub_group": [
        {
          "date": "2020-11-01",
          "group": "2020-11-01",
          "total_sent": 0,
          "total_received": 0,
          "total_billing_units": 0,
          "total_optout": 0
        }
      ]
    }
  ],
  "total_sent": 0,
  "total_received": 0,
  "total_billing_units": 0,
  "total_optout": 0
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/summary" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Post insights report

POST /v2-preview/reporting/messages/insights

Create report summary containing total number of sent, received and billing units, using pre-calculated data to improve performance.

• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.
• timezone The timezone of the messages to include, using the name of the region.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• source Filter results by source address.
• destination Filter results by destination address.
• metadata_key Filter results for messages that include a metadata key.
• metadata_value Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.
• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

• status Items Enum: UNDEFINED QUEUED PROCESSING PROCESSED FAILED SCHEDULED CANCELLED DELIVERED EXPIRED ENROUTE HELD SUBMITTED REJECTED READ

  An array of message statuses

• opt_out Filter the report to only include messages that triggered an opt out

• group_by Items Enum: ACCOUNT DAY WEEK MONTH YEAR METADATA_KEY METADATA_VALUE STATUS COUNTRY

  Group results by a list of values, from the enumerable table above.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Responses

200 — OK

Field	Type	Required	Description
summaries	array of object	No
total_sent	number	No
total_received	number	No
total_billing_units	number	No
total_optout	number	No

Example:

{
  "summaries": [
    {
      "group": "Account1",
      "total_sent": 0,
      "total_received": 0,
      "total_billing_units": 0,
      "total_optout": 0,
      "sub_group": [
        {
          "date": "2020-11-01",
          "group": "2020-11-01",
          "total_sent": 0,
          "total_received": 0,
          "total_billing_units": 0,
          "total_optout": 0
        }
      ]
    }
  ],
  "total_sent": 0,
  "total_received": 0,
  "total_billing_units": 0,
  "total_optout": 0
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/insights" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Post async detail report

POST /v2-preview/reporting/messages/async/detail

Generates an asynchronous report listing all sent and/or received messages within a specified time period.

• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.
• timezone The timezone of the messages to include, using the name of the region.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• source Filter results by source address.
• destination Filter results by destination address.
• metadata_key Filter results for messages that include a metadata key.
• metadata_value Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.
• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

• status Items Enum: UNDEFINED QUEUED PROCESSING PROCESSED FAILED SCHEDULED CANCELLED DELIVERED EXPIRED ENROUTE HELD SUBMITTED REJECTED READ

  An array of message statuses

• opt_out Filter the report to only include messages that triggered an opt out

• message_format Items Enum: MMS SMS TTS RCS CHANNEL

  Format of message type.

• fields Can be used for async detail report to select the fields to export csv files
• delivery_options A list of options to configure the delivery of the report.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
start_date	string	Yes	Inclusive (timestamp is greater than or equal)
end_date	string	Yes	Exclusive (timestamp is less than)
timezone	string	No	The standard timezone name
direction	enum: all, outbound, inbound	No
source	string	No
destination	string	No
metadata_key	string	No
metadata_value	string	No
accounts	array of object	No
status	array of object	No
opt_out	string	No
message_format	array of object	No
fields	array of object	No
delivery_options	array of object	No

Example

{
  "start_date": "2019-12-12T00:00:00.000+11:00",
  "end_date": "2019-12-14T00:00:00.000+11:00",
  "timezone": "Australia/Sydney",
  "direction": "all",
  "source": "+61555555555",
  "destination": "+61555555555",
  "metadata_key": "broadcastId",
  "metadata_value": "ABC",
  "accounts": [
    "Account1",
    "Account2"
  ],
  "status": [
    "UNDEFINED"
  ],
  "opt_out": "true",
  "message_format": [
    "SMS"
  ],
  "fields": [
    {
      "name": "id",
      "display_name": "id"
    }
  ],
  "delivery_options": [
    {
      "delivery_type": "EMAIL",
      "delivery_addresses": [
        "email@example.com"
      ],
      "delivery_format": "CSV"
    }
  ]
}

Responses

202 — Accepted

Field	Type	Required	Description
report_id	string	Yes

Example:

{
  "report_id": "51f0097f-90b2-4a59-ad88-a0fd93abaa82"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/async/detail" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2019-12-12T00:00:00.000+11:00","end_date":"2019-12-14T00:00:00.000+11:00","timezone":"Australia/Sydney","direction":"all","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","message_format":["SMS"],"fields":[{"name":"id","display_name":"id"}],"delivery_options":[{"delivery_type":"EMAIL","delivery_addresses":["email@example.com"],"delivery_format":"CSV"}]}'

Post async summary report

POST /v2-preview/reporting/messages/async/summary

Creates an asynchronous report summary containing total number of sent, received and billing units.

• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.
• timezone The timezone of the messages to include, using the name of the region.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• source Filter results by source address.
• destination Filter results by destination address.
• metadata_key Filter results for messages that include a metadata key.
• metadata_value Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided.
• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

• status Items Enum: UNDEFINED QUEUED PROCESSING PROCESSED FAILED SCHEDULED CANCELLED DELIVERED EXPIRED ENROUTE HELD SUBMITTED REJECTED READ

  An array of message statuses

• opt_out Filter the report to only include messages that triggered an opt out

• group_by Items Enum: ACCOUNT DAY WEEK MONTH YEAR METADATA_KEY METADATA_VALUE STATUS COUNTRY

  Group results by a list of values, from the enumerable table above.

• delivery_options A list of options to configure the delivery of the report.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
start_date	string	Yes	Inclusive (timestamp is greater than or equal)
end_date	string	Yes	Exclusive (timestamp is less than)
timezone	string	Yes
direction	enum: all, outbound, inbound	No
source	string	No
destination	string	No
metadata_key	string	No
metadata_value	string	No
accounts	array of object	No
status	array of object	No
opt_out	string	No
group_by	array of object	No
delivery_options	array of object	No

Example

{
  "start_date": "2019-12-12T00:00:00.000+11:00",
  "end_date": "2019-12-14T00:00:00.000+11:00",
  "timezone": "Australia/Sydney",
  "direction": "all",
  "source": "+61555555555",
  "destination": "+61555555555",
  "metadata_key": "broadcastId",
  "metadata_value": "ABC",
  "accounts": [
    "Account1",
    "Account2"
  ],
  "status": [
    "UNDEFINED"
  ],
  "opt_out": "true",
  "group_by": [
    "ACCOUNT"
  ],
  "delivery_options": [
    {
      "delivery_type": "EMAIL",
      "delivery_addresses": [
        "email@example.com"
      ],
      "delivery_format": "CSV"
    }
  ]
}

Responses

202 — Accepted

Field	Type	Required	Description
report_id	string	Yes

Example:

{
  "report_id": "51f0097f-90b2-4a59-ad88-a0fd93abaa82"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/async/summary" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2019-12-12T00:00:00.000+11:00","end_date":"2019-12-14T00:00:00.000+11:00","timezone":"Australia/Sydney","direction":"all","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","group_by":["ACCOUNT"],"delivery_options":[{"delivery_type":"EMAIL","delivery_addresses":["email@example.com"],"delivery_format":"CSV"}]}'

Get async detail report status

GET /v2-preview/reporting/messages/async/status

Retrieves the status of a detail report.

• report_id Example: report_id=abc

  The ID of the detail report to retrieve.

Authentication: basic_auth or hmac_auth

Request body

Request body as present in the Apiary dump (unusual for GET).

Optional.

Fields

Field	Type	Required	Description
(body)	string	No

Example

string

Responses

200 — OK

Field	Type	Required	Description
report_status	enum: REQUESTED, RUNNING, FAILED, CANCELLED, DONE	Yes

Example:

{
  "report_status": "DONE"
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/async/status" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '"string"'

Get async detail fields

POST /v2-preview/reporting/messages/async/detail/fields

Can be used for async detail report to select the fields to export csv files

• page Page number for paging through paginated result sets.
• page_size Number of results to return in a page for paginated result sets.
• start_date Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format.
• end_date End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date.

• direction Enum: inbound outbound all

  The type of messages to include in the report.

• accounts Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts.

Authentication: basic_auth or hmac_auth

Request body

Optional.

Responses

200 — OK

Field	Type	Required	Description
fields	array of object	Yes

Example:

{
  "fields": [
    "id",
    "content",
    "meta1"
  ]
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/messages/async/detail/fields" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Create a scheduled detail report

POST /v2-preview/reporting/detail/scheduled

Create scheduled report in detail containing total number of sent, received and billing units.

• label The label of the report schedule
• schedule The time schedule of a scheduled report
• report A scheduled detail report request.

• message_type Enum: inbound outbound all

  The type of messages to include in the report.

• report_type string
• metadata Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
label	string	Yes
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
report	object	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.delivery_options	array of object	No
message_type	enum: all, outbound, inbound	No
report_type	string	No
metadata	object	No
metadata.myKey	string	No
metadata.anotherKey	string	No

Example

{
  "label": "",
  "schedule": {
    "timezone": "Australia/Sydney",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [
      "Account1",
      "Account2"
    ],
    "status": [
      "UNDEFINED"
    ],
    "opt_out": "true",
    "delivery_options": [
      {
        "delivery_type": "EMAIL",
        "delivery_addresses": [
          "email@example.com"
        ],
        "delivery_format": "CSV"
      }
    ]
  },
  "message_type": "all",
  "report_type": "",
  "metadata": {
    "myKey": "myValue",
    "anotherKey": "anotherValue"
  }
}

Responses

201 — Created

Field	Type	Required	Description
scheduled_report_id	string	Yes

Example:

{
  "scheduled_report_id": "51f0097f-90b2-4a59-ad88-a0fd93abaa82"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/detail/scheduled" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"","schedule":{"timezone":"Australia/Sydney","cron_expression":"0 0 * * * ? *","type":"cron"},"report":{"period":"TODAY","timezone":"Australia/Sydney","direction":"all","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","delivery_options":[{"delivery_type":"EMAIL","delivery_addresses":["email@example.com"],"delivery_format":"CSV"}]},"message_type":"all","report_type":"","metadata":{"myKey":"myValue","anotherKey":"anotherValue"}}'

Update a scheduled detail report

PUT /v2-preview/reporting/detail/scheduled/{scheduled_id}

Updates a selected scheduled report in detail, which contains a total number of sent, received and billing units.

• scheduled_id Example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e

  The ID of the scheduled report to update.

• label The label of the report schedule
• schedule The time schedule of a scheduled report
• report A scheduled detail report request.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
scheduled_id	path	string	Yes	scheduled_id

Request body

Optional.

Fields

Field	Type	Required	Description
label	string	Yes
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
report	object	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.delivery_options	array of object	No

Example

{
  "label": "",
  "schedule": {
    "timezone": "Australia/Sydney",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [
      "Account1",
      "Account2"
    ],
    "status": [
      "UNDEFINED"
    ],
    "opt_out": "true",
    "delivery_options": [
      {
        "delivery_type": "EMAIL",
        "delivery_addresses": [
          "email@example.com"
        ],
        "delivery_format": "CSV"
      }
    ]
  }
}

Responses

200 — OK

Field	Type	Required	Description
label	string	Yes
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
report	object	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.delivery_options	array of object	No
message_type	enum: all, outbound, inbound	No
report_type	string	No
metadata	object	No
metadata.myKey	string	No
metadata.anotherKey	string	No

Example:

{
  "label": "",
  "schedule": {
    "timezone": "Australia/Sydney",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [
      "Account1",
      "Account2"
    ],
    "status": [
      "UNDEFINED"
    ],
    "opt_out": "true",
    "delivery_options": [
      {
        "delivery_type": "EMAIL",
        "delivery_addresses": [
          "email@example.com"
        ],
        "delivery_format": "CSV"
      }
    ]
  },
  "message_type": "all",
  "report_type": "",
  "metadata": {
    "myKey": "myValue",
    "anotherKey": "anotherValue"
  }
}

Example request

curl -X PUT "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/detail/scheduled/{scheduled_id}" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"","schedule":{"timezone":"Australia/Sydney","cron_expression":"0 0 * * * ? *","type":"cron"},"report":{"period":"TODAY","timezone":"Australia/Sydney","direction":"all","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","delivery_options":[{"delivery_type":"EMAIL","delivery_addresses":["email@example.com"],"delivery_format":"CSV"}]}}'

Create a scheduled summary report

POST /v2-preview/reporting/summary/scheduled

Create scheduled report summary containing total number of sent, received and billing units.

• label The label of the report schedule
• schedule The time schedule of a scheduled report
• report A scheduled summary report request.

• message_type Enum: inbound outbound all

  The type of messages to include in the report.

• report_type string
• metadata Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long

Authentication: basic_auth or hmac_auth

Request body

Optional.

Fields

Field	Type	Required	Description
label	string	Yes
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
report	object	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.group_by	array of object	No
report.delivery_options	array of object	No
message_type	enum: all, outbound, inbound	No
report_type	string	No
metadata	object	No
metadata.myKey	string	No
metadata.anotherKey	string	No

Example

{
  "label": "",
  "schedule": {
    "timezone": "Australia/Sydney",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [
      "Account1",
      "Account2"
    ],
    "status": [
      "UNDEFINED"
    ],
    "opt_out": "true",
    "group_by": [
      "ACCOUNT"
    ],
    "delivery_options": [
      {
        "delivery_type": "EMAIL",
        "delivery_addresses": [
          "email@example.com"
        ],
        "delivery_format": "CSV"
      }
    ]
  },
  "message_type": "all",
  "report_type": "",
  "metadata": {
    "myKey": "myValue",
    "anotherKey": "anotherValue"
  }
}

Responses

201 — Created

Field	Type	Required	Description
scheduled_report_id	string	Yes

Example:

{
  "scheduled_report_id": "51f0097f-90b2-4a59-ad88-a0fd93abaa82"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/summary/scheduled" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"","schedule":{"timezone":"Australia/Sydney","cron_expression":"0 0 * * * ? *","type":"cron"},"report":{"period":"TODAY","timezone":"Australia/Sydney","direction":"all","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","group_by":["ACCOUNT"],"delivery_options":[{"delivery_type":"EMAIL","delivery_addresses":["email@example.com"],"delivery_format":"CSV"}]},"message_type":"all","report_type":"","metadata":{"myKey":"myValue","anotherKey":"anotherValue"}}'

Update a scheduled summary report

PUT /v2-preview/reporting/summary/scheduled/{scheduled_id}

Updates a selected scheduled report summary, which contains a total number of sent, received and billing units.

• scheduled_id Example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e

  The ID of the scheduled report to update.

• label The label of the report schedule
• schedule The time schedule of a scheduled report
• report A scheduled summary report request.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
scheduled_id	path	string	Yes	scheduled_id

Request body

Optional.

Fields

Field	Type	Required	Description
label	string	Yes
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
report	object	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.group_by	array of object	No
report.delivery_options	array of object	No

Example

{
  "label": "",
  "schedule": {
    "timezone": "Australia/Sydney",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [
      "Account1",
      "Account2"
    ],
    "status": [
      "UNDEFINED"
    ],
    "opt_out": "true",
    "group_by": [
      "ACCOUNT"
    ],
    "delivery_options": [
      {
        "delivery_type": "EMAIL",
        "delivery_addresses": [
          "email@example.com"
        ],
        "delivery_format": "CSV"
      }
    ]
  }
}

Responses

200 — OK

Field	Type	Required	Description
label	string	Yes
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
report	object	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.group_by	array of object	No
report.delivery_options	array of object	No
message_type	enum: all, outbound, inbound	No
report_type	string	No
metadata	object	No
metadata.myKey	string	No
metadata.anotherKey	string	No

Example:

{
  "label": "",
  "schedule": {
    "timezone": "Australia/Sydney",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [
      "Account1",
      "Account2"
    ],
    "status": [
      "UNDEFINED"
    ],
    "opt_out": "true",
    "group_by": [
      "ACCOUNT"
    ],
    "delivery_options": [
      {
        "delivery_type": "EMAIL",
        "delivery_addresses": [
          "email@example.com"
        ],
        "delivery_format": "CSV"
      }
    ]
  },
  "message_type": "all",
  "report_type": "",
  "metadata": {
    "myKey": "myValue",
    "anotherKey": "anotherValue"
  }
}

Example request

curl -X PUT "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/summary/scheduled/{scheduled_id}" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"label":"","schedule":{"timezone":"Australia/Sydney","cron_expression":"0 0 * * * ? *","type":"cron"},"report":{"period":"TODAY","timezone":"Australia/Sydney","direction":"all","source":"+61555555555","destination":"+61555555555","metadata_key":"broadcastId","metadata_value":"ABC","accounts":["Account1","Account2"],"status":["UNDEFINED"],"opt_out":"true","group_by":["ACCOUNT"],"delivery_options":[{"delivery_type":"EMAIL","delivery_addresses":["email@example.com"],"delivery_format":"CSV"}]}}'

GET active reports

GET /v2-preview/reporting/scheduled

Retrieves all ACTIVE scheduled reports of a provided account.

+ page_size Example: page_size=1

              Number of results to return in a page for paginated result sets.

+ page_token Returned by Chronos service

Authentication: basic_auth or hmac_auth

Request body

Request body as present in the Apiary dump (unusual for GET).

Optional.

Fields

Field	Type	Required	Description
(body)	number	No

Example

0

Responses

200 — OK

Field	Type	Required	Description
pagination	object	No
pagination.page_token	string	Yes
pagination.page_size	number	Yes
data	array of object	No

Example:

{
  "pagination": {
    "page_token": "abc123",
    "page_size": 20
  },
  "data": [
    {
      "label": "TODAY_MT_RECEIVED",
      "report": {
        "period": "TODAY",
        "timezone": "Australia/Sydney",
        "direction": "all",
        "source": "+61555555555",
        "destination": "+61555555555",
        "metadata_key": "broadcastId",
        "metadata_value": "ABC",
        "accounts": [
          "Account1",
          "Account2"
        ],
        "status": [
          "UNDEFINED"
        ],
        "opt_out": "true",
        "group_by": [
          "ACCOUNT"
        ],
        "delivery_options": [
          {
            "delivery_type": "EMAIL",
            "delivery_addresses": [
              "email@example.com"
            ],
            "delivery_format": "CSV"
          }
        ]
      },
      "schedule": {
        "timezone": "`UTC",
        "cron_expression": "0 0 12 1/1 * ? *",
        "type": "cron"
      },
      "scheduled_report_id": "b05b41ec-c0d4-47ce-afc1-fab579d4ac5c",
      "message_type": "sent messages",
      "report_type": "detail"
    }
  ]
}

404 — Not Found

Field	Type	Required	Description
message	string	No
details	array of string	No

Example:

{
  "message": "Resource not found",
  "details": [
    "Scheduled report not found"
  ]
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/scheduled" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '0'

Get scheduled report by Id

GET /v2-preview/reporting/scheduled/{scheduled_id}

Retrieves a scheduled report by providing its id.

• scheduled_id Example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e

  The ID of the scheduled report to retrieve.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
scheduled_id	path	string	Yes	scheduled_id

Request body

Request body as present in the Apiary dump (unusual for GET).

Optional.

Fields

Field	Type	Required	Description
(body)	string	No

Example

string

Responses

200 — OK

Field	Type	Required	Description
label	string	Yes
report	scheduleddsummaryrequest	No
report.period	enum: TODAY, YESTERDAY, THIS_WEEK, LAST_WEEK, THIS_MONTH, LAST_MONTH, LAST_30_DAYS, LAST_7_DAYS, THIS_WEEKDAYS, LAST_WEEKDAYS	Yes
report.timezone	string	No	The standard timezone name
report.direction	enum: all, outbound, inbound	No
report.source	string	No
report.destination	string	No
report.metadata_key	string	No
report.metadata_value	string	No
report.accounts	array of object	No
report.status	array of object	No
report.opt_out	string	No
report.group_by	array of object	No
report.delivery_options	array of object	No
schedule	object	Yes
schedule.timezone	string	Yes
schedule.cron_expression	string	Yes
schedule.type	string	Yes
scheduled_report_id	string	No	c381-4943-8619-f10460005898
message_type	enum: all, outbound, inbound	No
report_type	string	No	detail or summary

Example:

{
  "label": "string",
  "report": {
    "period": "TODAY",
    "timezone": "Australia/Sydney",
    "direction": "all",
    "source": "+61555555555",
    "destination": "+61555555555",
    "metadata_key": "broadcastId",
    "metadata_value": "ABC",
    "accounts": [],
    "status": [],
    "opt_out": "true",
    "group_by": [],
    "delivery_options": []
  },
  "schedule": {
    "timezone": "UTC",
    "cron_expression": "0 0 * * * ? *",
    "type": "cron"
  },
  "scheduled_report_id": "43928f76",
  "message_type": "all",
  "report_type": "detail"
}

404 — Not Found

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/scheduled/{scheduled_id}" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '"string"'

Delete a scheduled report

DELETE /v2-preview/reporting/scheduled/{scheduled_id}

Deletes a scheduled report by providing its id.

• scheduled_id Example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e

  The ID of the scheduled report to delete.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
scheduled_id	path	string	Yes	uuid of schedule report

Responses

200 — OK

404 — Not Found

Example request

curl -X DELETE "https://api.messaging.tpgtelecom.com.au/v2-preview/reporting/scheduled/'uuid'" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Replies

Replies operations.

Check replies

GET /v1/replies

Check for any replies that have been received.

Replies are messages that have been sent from a handset in response to a message sent by an application or messages that have been sent from a handset to a inbound number associated with an account, known as a dedicated inbound number (contact <support@messaging.tpgtelecom.com.au> for more information on dedicated inbound numbers).

Each request to the check replies endpoint will return any replies received that have not yet been confirmed using the confirm replies endpoint. A response from the check replies endpoint will have the following structure:

{
    "replies": [
        {
            "metadata": {
                "myKey": "myValue",
                "anotherKey": "anotherValue"
            },
            "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
            "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74",
            "date_received": "2022-12-07T08:43:00.850Z",
            "callback_url": "https://my.callback.url.com",
            "destination_number": "+61491570156",
            "source_number": "+61491570157",
            "vendor_account_id": {
                "vendor_id": "TPGTelecom",
                "account_id": "MyAccount"
            },
            "content": "My first reply!"
        },
        {
            "metadata": {
                "myKey": "myValue",
                "anotherKey": "anotherValue"
            },
            "message_id": "8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4",
            "reply_id": "3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f",
            "date_received": "2022-12-07T08:43:00.850Z",
            "callback_url": "https://my.callback.url.com",
            "destination_number": "+61491570157",
            "source_number": "+61491570158",
            "vendor_account_id": {
                "vendor_id": "TPGTelecom",
                "account_id": "MyAccount"
            },
            "content": "My second reply!"
        }
    ]
}

Each reply will contain details about the reply message, as well as details of the message the reply was sent in response to, including any metadata specified. Every reply will have a reply ID to be used with the confirm replies endpoint.

Note: The source number and destination number properties in a reply are the inverse of those specified in the message the reply is in response to. The source number of the reply message is the same as the destination number of the original message, and the destination number of the reply message is the same as the source number of the original message. If a source number wasn't specified in the original message, then the destination number property will not be present in the reply message.

Subsequent requests to the check replies endpoint will return the same reply messages and a maximum of 100 replies will be returned in each request. Applications should use the confirm replies endpoint in the following pattern so that replies that have been processed are no longer returned in subsequent check replies requests. The expiry date for getting an entity is 45 days.

1. Call check replies endpoint
2. Process each reply message
3. Confirm all processed reply messages using the confirm replies endpoint

Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check replies endpoint.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
Accept	header	string	No	e.g. application/json

Responses

200 — Unconfirmed replies

Field	Type	Required	Description
replies	array of object	No	The oldest 100 unconfirmed replies
replies[].callback_url	string	No	The URL specified as the callback URL in the original submit message request
replies[].content	string	No	Content of the reply
replies[].date_received	string	No	Date time when the reply was received
replies[].destination_number	string	No	Address from which this reply was sent to
replies[].message_id	string	No	Unique ID of the original message
replies[].metadata	object	No	Any metadata that was included in the original submit message request
replies[].reply_id	string	No	Unique ID of this reply
replies[].source_number	string	No	Address from which this reply was received from
replies[].vendor_account_id	object	No
replies[].vendor_account_id.vendor_id	string	No
replies[].vendor_account_id.account_id	string	No	The account used to submit the original message.

Example:

{
  "replies": [
    {
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      },
      "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
      "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74",
      "date_received": "2022-12-07T08:43:00.850Z",
      "callback_url": "https://my.callback.url.com",
      "destination_number": "+61491570156",
      "source_number": "+61491570157",
      "vendor_account_id": {
        "vendor_id": "TPGTelecom",
        "account_id": "MyAccount"
      },
      "content": "My first reply!"
    },
    {
      "metadata": {
        "myKey": "myValue",
        "anotherKey": "anotherValue"
      },
      "message_id": "8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4",
      "reply_id": "3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f",
      "date_received": "2022-12-07T08:43:00.850Z",
      "callback_url": "https://my.callback.url.com",
      "destination_number": "+61491570157",
      "source_number": "+61491570158",
      "vendor_account_id": {
        "vendor_id": "TPGTelecom",
        "account_id": "MyAccount"
      },
      "content": "My second reply!"
    }
  ]
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Resource not found"
}

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/replies" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Confirm replies as received

POST /v1/replies/confirmed

Mark a reply message as confirmed so it is no longer returned in check replies requests.

The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint to allow for robust processing of reply messages. Once one or more reply messages have been processed they can then be confirmed using the confirm replies endpoint so they are no longer returned in subsequent check replies requests.

The confirm replies endpoint takes a list of reply IDs as follows:

{
    "reply_ids": [
        "011dcead-6988-4ad6-a1c7-6b6c68ea628d",
        "3487b3fa-6586-4979-a233-2d1b095c7718",
        "ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
    ]
}

The expiry date for getting an entity is 45 days. Up to 100 replies can be confirmed in a single confirm replies request.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
Accept	header	string	No	e.g. application/json

Request body

Optional.

Example

{
  "reply_ids": [
    "011dcead-6988-4ad6-a1c7-6b6c68ea628d",
    "3487b3fa-6586-4979-a233-2d1b095c7718",
    "ba28e94b-c83d-4759-98e7-ff9c7edb87a1"
  ]
}

Responses

202 — Requested replies will be marked as confirmed

400 — Bad request

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Request failed to parse correctly. Please ensure input is valid and try again."
}

403 — Unauthorised

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Invalid authentication credentials"
}

404 — Resource not found

Field	Type	Required	Description
message	string	No

Example:

{
  "message": "Resource not found"
}

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/replies/confirmed" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>" \
  -H "Content-Type: application/json" \
  -d '{"reply_ids":["011dcead-6988-4ad6-a1c7-6b6c68ea628d","3487b3fa-6586-4979-a233-2d1b095c7718","ba28e94b-c83d-4759-98e7-ff9c7edb87a1"]}'

Webhooks

The Webhooks Management API allows you to manage your webhooks configuration. You can subscribe to one or several events, retrieve the webhooks, update them or even delete them if needed.

Notifications

If a callback URL is specified in the submit message request, then changes to the message status, replies received in response to the message or delivery reports received for the message will be pushed via a HTTP POST request.

Format

All notifications are JSON encoded and the request expects to receive a response in the HTTP 200 range. If a valid response isn't received the request will be retried in an exponentially backing off fashion.

Delivery Reports

For delivery reports or changes in the status of a message, the POST request to the specified URL will be as follows: Note, multiple delivery report notifications will be recieved for a single message.

Create Webhook

POST /v1/webhooks/messages

Create a webhook for one or more of the specified events.

A webhook would typically have the following structure:

{
  "url": "http://webhook.com",
  "method": "POST",
  "encoding": "JSON",
  "headers": {
    "Account": "DeveloperPortal7000"
  },
  "events": [
    "RECEIVED_SMS"
  ],
  "template": "{\"id\":\"$mtId\"    }",
  "read_timeout": 5000,
  "retries": 3,
  "retry_delay": 30
}

A valid webhook must consist of the following properties:

• url The configured URL which will trigger the webhook when a selected event occurs.
• method The methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests.
• encoding Webhooks can be delivered using different content types. You can choose from JSON, FORM_ENCODED or XML. This will automatically add the Content-Type header for you so you don't have to add it again in the headers property.
• headers HTTP header fields which provide required information about the request or response, or about the object sent in the message body. This should NOT include the Content-Type header.
• events Event or events that will trigger the webhook. At least one event should be present.
• template The structure of the payload that will be returned. You can format this in JSON or XML.
• read_timeout (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000.
• retries (Optional) The number of times the Webhook request should retry. Set to 0 by default, max 5.
• retry_delay (Optional) The delay period between retries in seconds. Minimum of 5, max 60

Types of Events

You can select all of the events (listed below) or combine them in whatever way you like but atleast one event must be used. Otherwise, the webhook won't be created.

A webhook will be triggered when any one or more of the events occur:

+ SMS

+ `RECEIVED_SMS` Receive an SMS
+ `OPT_OUT_SMS` Opt-out occured

+ MMS

+ `RECEIVED_MMS` Receive an MMS

+ DR (Delivery Reports)

+ `ENROUTE_DR` Message is enroute
+ `EXPIRED_DR` Message has expired
+ `REJECTED_DR` Message is rejected
+ `FAILED_DR` Message has failed
+ `DELIVERED_DR` Message is delivered
+ `SUBMITTED_DR` Message is submitted

Template Parameters

You can choose what to include in the data that will be sent as the payload via the Webhook. It's upto you to choose what format you would like the payload to be returned. You can choose between JSON or XML. Keep in my mind, if you've chosen JSON as the format, you must escape the JSON in the template value (see example above).

The table illustrates a list of all the parameters that can be included in the template and which event types it can be applied to.

Data	Parameter Name	Example	Event Type
Service Type	$type	SMS	DR MO MO MMS
Message ID	$mtId, $messageId	877c19ef-fa2e-4cec-827a-e1df9b5509f7	DR MO MO MMS
Delivery Report ID	$drId, $reportId	01e1fa0a-6e27-4945-9cdb-18644b4de043	DR
Reply ID	$moId, $replyId	a175e797-2b54-468b-9850-41a3eab32f74	MO MO MMS
Account ID	$accountId	DeveloperPortal7000	DR MO MO MMS
Message Timestamp	$submittedTimestamp	2022-12-07T08:43:00.850Z	DR MO MO MMS
Provider Timestamp	$receivedTimestamp	2022-12-07T08:44:00.850Z	DR MO MO MMS
Message Status	$status	enroute	DR
Status Code	$statusCode	200	DR
External Metadata	$metadata.get('key')	name	DR MO MO MMS
Source Address	$sourceAddress	+61491570156	DR MO MO MMS
Destination Address	$destinationAddress	+61491593156	MO MO MMS
Message Content	$mtContent, $messageContent	Hi John	DR MO MO MMS
Reply Content	$moContent, $replyContent	Hello Jane	MO MO MMS
Retry Count	$retryCount	1	DR MO MO MMS

Note: A 400 response will be returned if the url is invalid, the events, encoding or method is null or the headers has a Content-Type attribute.

Message Statuses

Delivery Reports indicate message status. A message can have one of the following statuses:

• enroute: Message has been received by the gateway and is being processed (or waiting to be processed).
• submitted: Message has been submitted to a provider/carrier for delivery.
• delivered: Message delivery has been confirmed by the provider, including to the handset (where possible).
• expired: The message has expired.
• rejected: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered
• failed: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider.

Message Status Codes

Status codes provide more granular insight into a message's status. A message can have one of the following status codes:

• 101: Message being processed by the gateway.
• 102: Message is being rerouted to a different provider after failing via the first provider.
• 151: Message held for screening.
• 200: Message submitted to downstream provider for delivery.
• 210: Message accepted by downstream provider.
• 211: Message is enroute for delivery by provider.
• 212: Message submitted. Delivery pending.
• 213: Message scheduled for delivery by downstream provider.
• 220: Message delivered.
• 221: Message delivered to the handset.
• 320: Message validity period has expired (prior to submission).
• 401: Message validity period has expired (before delivery).
• 301: Usage threshold reached. Message discarded.
• 302: Destination address blocked. Message discarded.
• 303: Source address blocked. Message discarded.
• 304: Message dropped. Contact support.
• 305: Message discarded due to duplicate detection.
• 402: Message rejected by downstream provider.
• 403: Message skipped by downstream provider.
• 410: Invalid source address.
• 411: Invalid destination address.
• 412: Destination address blocked.
• 413: SMS service unavailable on destination.
• 414: Destination unreachable.
• 330: Gateway failure.
• 331: Message discarded.
• 332: No available route to destination.
• 333: Source address unsupported for this destination.
• 400: Message failed; undeliverable.
• 405: Message cancelled or deleted by provider.

Authentication: basic_auth or hmac_auth

Responses

201 — Webhook successfully created

400 — Request was invalid

409 — Duplicate webhook

Example request

curl -X POST "https://api.messaging.tpgtelecom.com.au/v1/webhooks/messages" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Retrieve Webhook

GET /v1/webhooks/messages/

Retrieve all the webhooks created for the connected account. A successful request to the retrieve webhook endpoint will return a response body as follows:

{
    "page": 0,
    "pageSize": 100,
    "pageData": [
        {
            "url": "https://webhook.com",
            "method": "POST",
            "id": "8805c9d8-bef7-41c7-906a-69ede93aa024",
            "encoding": "JSON",
            "events": [
                "RECEIVED_SMS"
            ],
            "headers": {},
            "template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}",
            "read_timeout": 5000,
            "retries": 3,
            "retry_delay": 30
        }
    ]
}

Note: Response 400 is returned when the page query parameter is not valid or the pageSize query parameter is not valid.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
page	query	string	No
pageSize	query	string	No

Responses

200 — OK

400 — Unexpected error in API call. See HTTP response body for details.

Example request

curl -X GET "https://api.messaging.tpgtelecom.com.au/v1/webhooks/messages/?page='0'&pageSize='10'" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Update Webhook

PATCH /v1/webhooks/messages/{webhookId}

Update a webhook. You can update individual attributes or all of them by submitting a PATCH request to the /webhooks/messages endpoint (the same endpoint used above to delete a webhook)

A successful request to the retrieve webhook endpoint will return a response body as follows:

{
    "url": "https://webhook.com",
    "method": "POST",
    "id": "04442623-0961-464e-9cbc-ec50804e0413",
    "encoding": "JSON",
    "events": [
        "RECEIVED_SMS"
    ],
    "headers": {},
    "template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}"
}

Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
webhookId	path	string	Yes

Responses

200 — Webhook updated successfully

400 — Unexpected error in API call. See HTTP response body for details.

404 — Webhook not found

Example request

curl -X PATCH "https://api.messaging.tpgtelecom.com.au/v1/webhooks/messages/a7f11bb0-f299-4861-a5ca-9b29d04bc5ad" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"

Delete Webhook

DELETE /v1/webhooks/messages/{webhookId}

Delete a webhook that was previously created for the connected account. A webhook can be cancelled by appending the UUID of the webhook to the endpoint and submitting a DELETE request to the /webhooks/messages endpoint.

A successful request to the retrieve webhook endpoint will return a null response.

Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.

Authentication: basic_auth or hmac_auth

Parameters

Name	In	Type	Required	Description
webhookId	path	string	Yes

Responses

204 — Webhook deleted successfully

404 — Webhook not found

Example request

curl -X DELETE "https://api.messaging.tpgtelecom.com.au/v1/webhooks/messages/a7f11bb0-f299-4861-a5ca-9b29d04bc5ad" \
  -H "Accept: application/json" \
  -H "Authorization: Basic <base64(api_key:api_secret)>"