TopMessage API Documentation |Status Codes

Security

When setting up webhook endpoints, you can secure your application against unwanted requests by configuring webhook secret. Each request signature is created using the HMAC_SHA256 hashing algorithm. The algorithm signs the webhook payload with the secret you have provided. The resulting hash is included in the request’s signature header in the following format:

X-TopMessage-Signature: {TOPMESSAGE_HMAC_SIGNATURE}

Manage your webhook endpoints

here

Receive Delivery Report

The delivery report of outgoing messages are sent to your webhook endpoint, indicating whether each message was successfully delivered or failed.

Name	Type	Description
data	`object`	Contains message information.

Data Object

Name	Type	Description
id	`string`	Unique identifier of your message.
status	`string`	Initial status of your message. Possible values: `PENDING`, `FAILED`, `DELIVERED`, `SEEN`
channel	`string`	The communication channel your message sent through. Possible values: `SMS` and `WHATSAPP` Default: `SMS`
type	`string`	Type of event related to the message.

Receive Incoming Message

Incoming messages received on your SMS or WhatsApp phone number are forwarded in real-time to the specified webhook endpoint.

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.
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.
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`
type	`string`	Type of event related to the message.

POST

https://{your_domain}/your_webhook/path

X-Topmessage-Signature: {TOPMESSAGE_HMAC_SIGNATURE}
Content-Type: application/json

Request Sample (Delivery Report)

Payload

Java

Python

{
    "data": {
        "id": "b04fc4d3-f232-46b7-b66b-538c0d4b3404",
        "status": "DELIVERED",
        "channel": "SMS",
        "type": "STATUS"
    }
}

Request Sample (Incoming Message)

Payload

Java

Python

{
    "data": {
        "id": "e3fc3b55-807f-41cf-93cf-cd365fef8515",
        "account_id": "1fc57cdd-64e7-4964-af14-4eef35717bac",
        "from": "491511234567",
        "to": "111511234567",
        "text": "Received",
        "channel": "WHATSAPP",
        "type": "MESSAGE"
    }
}