TopMessage API Documentation

Authentication

When making API requests, you need to include your API key in the HTTP header. The header format should look like this:

X-TopMessage-Key: {API_KEY}

Manage your API keys

here

Send Messages

Easily send one or more messages to your customers via their preferred channels, such as SMS and WhatsApp, using a single, unified API. Start with a simple text message by defining the destination and content, or leverage advanced features to enhance your communication strategy.

Use Case Examples

The following are some examples of use cases for the TopMessage API:

Full Request Parameters

Name	Type	Description
data	`object`	Contains message information.

Data Object

Name	Type	Description
from	`string`	The name your message will appear to be sent from. You can customize it with your company name (up to 11 characters) or use a virtual number. Go to Senders page TopMessage
to	`string[]`	The recipient's mobile phone number(s) in international format. 111511234567
text	`string`	Your message text to be sent to the recipient(s). Hi there! Just testing out this cool SMS feature. https://topmessage.com

Full Response Parameters

The response includes all parameters from the request, along with the additional parameters listed below.

Data Object

Name	Type	Description
id	`string`	Unique identifier of your message. 0f15fa5d-97ef-46d5-844a-f507f1c4c461
account_id	`string`	Unique identifier of your account. 0d1f7f1c-27df-41bf-8bdc-5666608a4285
from	`string`	The name your message will appear to be sent from. You can customize it with your company name (up to 11 characters) or use a virtual number. Go to Senders page TopMessage
to	`string[]`	The recipient's mobile phone number(s) in international format. 111511234567
text	`string`	Your message text to be sent to the recipient(s). Hi there! Just testing out this cool SMS feature. https://topmessage.com
channel	`string`	The communication channel your message sent through. Possible values: `SMS` and `WHATSAPP` Default: `SMS` SMS
segment_count	`integer`	The number of segments your message consisted of. 1
encoding	`string`	Encoding of your message. Possible values: `STANDARD` and `UNICODE` STANDARD
schedule	`string`	Specifies the time when the message should be sent. The time must be in UTC and follow the ISO-8601 format ("2024-12-01T18:00:00Z"). The scheduled time cannot be set for more than 1 year in the future. Default: Now 2024-11-10T08:11:46Z
create_date	`string`	Time when the message was initiated 2024-11-10T08:11:46Z
update_date	`string`	Last status update date of your message. 2024-11-10T08:11:46Z

POST

https://api.topmessage.com/v1/messages

X-TopMessage-Key: {API_KEY}
Content-Type: application/json

Request Sample

Payload

cURL

Java

Python

{
    "data": {
        "from": "TopMessage",
        "to": [
            "111511234567"
        ],
        "text": "Hi there! Just testing out this cool SMS feature. https://topmessage.com"
    }
}

Response Sample

{
    "data": [
        {
            "id": "0f15fa5d-97ef-46d5-844a-f507f1c4c461",
            "account_id": "0d1f7f1c-27df-41bf-8bdc-5666608a4285",
            "from": "TopMessage",
            "to": "111511234567",
            "text": "Hi there! Just testing out this cool SMS feature. https://topmessage.com",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "schedule": "2024-11-10T08:11:46Z",
            "create_date": "2024-11-10T08:11:46Z",
            "update_date": "2024-11-10T08:11:46Z"
        }
    ]
}