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:

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

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.

Name	Type	Description
data	`object`	Contains message information.

Data Object

Name	Type	Description
id	`string`	Unique identifier of your message.
account_id	`string`	Unique identifier of your account.
status	`string`	Initial status of your message. Possible values: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
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
to	`string[]`	The recipient's mobile phone number(s) in international format.
text	`string`	Your message text to be sent to the recipient(s).
channel	`string`	The communication channel your message sent through. Possible values: `SMS` and `WHATSAPP` Default: `SMS`
segment_count	`integer`	The number of segments your message consisted of.
encoding	`string`	Encoding of your message. Possible values: `STANDARD` and `UNICODE`
direction	`string`	Indicates the flow of the message — whether it was sent by your system or received from a user. Possible values: `OUTBOUND`, `INBOUND`
country	`string`	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.
type	`string`	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.
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
create_date	`string`	Time when the message was initiated
update_date	`string`	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

{
    "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"
        }
    ]
}