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:

Send a single SMS message—perfect for direct, one-to-one communication like alerts or confirmations.

Full Request Parameters

NameTypeDescription
dataobject
Contains message information.
Data Object
NameTypeDescription
fromstring
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
tostring[]
The recipient's mobile phone number(s) in international format.
111511234567
textstring
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.
NameTypeDescription
dataobject
Contains message information.
Data Object
NameTypeDescription
idstring
Unique identifier of your message.
account_idstring
Unique identifier of your account.
statusstring
Initial status of your message.
Possible values: PENDING, FAILED, DELIVERED, SEEN
fromstring
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

tostring[]
The recipient's mobile phone number(s) in international format.
textstring
Your message text to be sent to the recipient(s).
channelstring
The communication channel your message sent through.
Possible values: SMS and WHATSAPP
Default: SMS
segment_countinteger
The number of segments your message consisted of.
encodingstring
Encoding of your message.
Possible values: STANDARD and UNICODE
directionstring
Indicates the flow of the message — whether it was sent by your system or received from a user.
Possible values: OUTBOUND, INBOUND
countrystring
Specifies the country of the recipient for outbound messages and the country of the sender for inbound messages. The value is provided in ISO 3166-1 alpha-2 format.
typestring
Indicates the type of message content being sent or received. This helps identify whether the message is a plain text, template-based, or media message (such as images or videos), including interactive content for WhatsApp.
schedulestring
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
create_datestring
Time when the message was initiated
update_datestring
Last status update date of your message.
POST
https://api.topmessage.com/v1/messages
X-TopMessage-Key: {API_KEY}
Content-Type: application/json
Request Sample

Payload

cURL

Java

Python

PHP

Node.js

C#

{
    "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",
            "status": "PENDING",
            "from": "TopMessage",
            "to": "111511234567",
            "text": "Hi there! Just testing out this cool SMS feature. https://topmessage.com",
            "channel": "SMS",
            "segment_count": "1",
            "encoding": "STANDARD",
            "direction": "OUTBOUND",
            "country": "US",
            "type": "text",
            "schedule": "2024-11-10T08:11:46Z",
            "create_date": "2024-11-10T08:11:46Z",
            "update_date": "2024-11-10T08:11:46Z"
        }
    ]
}