Skip to content

Knowledge Base

Knowledge Base

SMS API Overview

BestSMS provides public APIs for developers to integrate BestSMS's enhanced messaging tools into their software applications. The API supports various methods, including REST, HTTP GET/POST, and Email.

BestSMS API uses the HTTP Authorization Header with the BASIC keyword for authentication, please follow How to Get API Auth Tokens to get your Auth Token.

 

Sending Messages

API Request Structure:

URL:

https://api.bestsms.com.au/api/v2.04/send/sms

Headers:

Content-Type="application/json; encoding='utf-8'"
Accept="application/json; encoding='utf-8'"
Authorization="BASIC [[Your Auth Token]]"

JSON body:

{
    "MessageData": {
        "Message": "Hello, this is a test message from Department01. Thank you.",
        "Destinations": [
            { "Recipient": "+614221000002" }
        ]
    }
}
 
 
Key Features:
  • Authorisation/APIKey:
    • Newer API versions use an Authorisation HTTP Header. Generate the Authorisation token via your dashboard login.
    • Older versions use a Sender/APIKey within the API call body. Unlimited APIKeys can be set up, optionally one per application.
  • Multiple Destinations:
    • Messages can be sent to individual or multiple recipients simultaneously (broadcast).
  • MessageID:
    • Utilised for mapping sent messages with results and replies in webhooks or polls.
  • Webhook Callback URL:
    • Specify the URL for webhook delivery if configured.
  • SubAccount and Department:
    • Useful for tracking costs and re-billing when sending messages on behalf of customers.
  • Personalisation:
    • Include first names, company names, and more in messages for personalised broadcasts.
  • Sending Time:
    • Schedule messages for delayed sending if needed.

 

Webhooks & Polls

Capture status and reply data using webhooks and polls. The MessageID is useful for matching results.

Example API Request for Status and Reply Data:

URL:

https://api.bestsms.com.au/api/v2.04/get/status/AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD

Headers:

Content-Type="application/json; encoding='utf-8'"
Accept="application/json; encoding='utf-8'"
Authorization="BASIC [[Your Auth Token]]"

Example Response:

{
    "Result": "Success",
    "MessageID": "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    "Status": "Completed",
    "JobNum": "Completed",
    "Account": "100001",
    "SubAccount": "",
    "Department": "",
    "Reference": "",
    "Created": "2024-06-13T06:44:16",
    "CreatedUTC": "2023-06-12T20:44:16",
    "Delayed": "2024-06-13T06:44:16",
    "DelayedUTC": "2023-06-12T20:44:16",
    "Timezone": "AUS Eastern",
    "Count": 1,
    "Complete": 1,
    "Success": 1,
    "Failed": 0,
    "Price": 0.1,
    "TotalRecords": 1,
    "RecordsPerPage": 100,
    "PageCount": 1,
    "Page": 1,
    "Recipients": [
        {
            "Type": "Text",
            "DestSeq": "00000001",
            "Destination": "+61410010001",
            "Status": "Success",
            "Result": "delivered",
            "SentDate": "2023-06-13T06:44:30",
            "SentDateUTC": "2023-06-12T20:44:30",
            "Attention": "",
            "Company": "",
            "Custom1": "",
            "Custom2": "",
            "Custom3": "",
            "Custom4": "",
            "Custom5": "",
            "Custom6": "",
            "Custom7": "",
            "Custom8": "",
            "Custom9": "",
            "RemoteID": "",
            "Price": 0.04
        }
    ]
}

 

Versioning

  • API Versioning: Specified in the URL of your API calls.
  • Flexibility: You can use any API version, allowing for easier upgrades.
  • Documentation: Includes a Versioning section with a ChangeLog.

 

Cost Tracking & Rebilling

  • SubAccount and Department Fields: Include these fields in API calls for tracking and rebilling.
  • Webhooks: Display SubAccount and Department used.
  • Dashboard Segmentation: Users can view their own usage reports.
  • Administrator View: Itemised usage by SubAccount or Department.
  • Wholesale CDR Reports: Note SubAccount and Department for rebilling.
  • Invoices: Optionally summarised by SubAccount.

 

Number Formatting

  • International Format (E.164): Recommended format, e.g., +61410010001, +61420010001.
  • Australian Formatting: Acceptable formats include:
    • +61410010001
    • 0061400010001
    • 61400010001
    • 0400010001
    • 400010001
  • API Flexibility: Able to strip unnecessary characters such as dashes and brackets.

 

By leveraging the BestSMS API, developers can efficiently integrate SMS messaging capabilities into their applications, ensuring a seamless communication experience.