Download OpenAPI specification:Download
Message Centre facilitates the sending of SMS messages to users through an API interface. This document details the endpoints and how to use them.
Messages will be split and sent as multiple concatenated message parts if the message exceeds the character limit for a given format.
By default messages will be automatically split, if you wish to have this feature disabled, please email support@msgcentre.com.
The supported character formats are:
GSM-7: This is the default format and a single message has a character limit of 160 characters. Concatenated messages are limited to 153 characters per message.
GSM-7 Extended: There is an extended set of characters that can be used in conjunction with regular GSM-7 characters, however these extended characters count as 2 characters each.
These characters are | ^ € { } [ ] ~ \
Unicode: This format will be used for establishing number of messages when a non GSM-7 character is detected.
Unicode messages have a character limit of 70 characters for a single message. Concatenated messages are limited to 67 characters per message.
By default clients will have Unicode character replacement enabled - this makes some common replacements on the message in attempt to make the message GSM-7 format, thus reducing the unexpected expansion to multiple messages.
The characters selected are common in tools such as Microsoft Office that automatically changes certain characters to improve the appearance of the email or document.
These replacements are as follows:
| Original Character Description | Original Character | Replaced Character | Replaced Character Description |
|---|---|---|---|
| En dash | – (U+2013) | - (0x2D) | Hyphen-Minus |
| Em dash | — (U+2014) | - (0x2D) | Hyphen-Minus |
| Left double quotation mark | “ (U+201C) | " (0x22) | Quotation Mark |
| Right double quotation mark | ” (U+201D) | " (0x22) | Quotation Mark |
| Left single quotation mark | ‘ (U+2018) | ' (0x27) | Apostrophe |
| Right single quoation mark | ’ (U+2019) | ' (0x27) | Apostrophe |
If you wish to disable Unicode character replacement, please contact us at support@msgcentre.com.
You can use our SMS length calculator to preview the format and length of a message.
The endpoints listed below are accessible via the base URL https://api.msgcentre.com.
Send an SMS message to the desired recipient.
| From required | string <= 21 characters Who the message should appear to be from. If non-numeric it must not exceed 11 characters in length. If numeric it is allowed up to 21 characters. From and To parameters cannot be the same. |
| To required | string The destination mobile number in international format, for example |
| Message required | string The content of the SMS message to be sent. If the message contains non-GSM characters client needs to have "allow Unicode" feature turned on. For GSM character set, max limit is 160 characters. For Unicode character set, max limit is 70 characters. For further information on this please read the above summary. |
| Scheduled | string The date and time the message should be sent. If this value is not provided or is in the past, the message will be sent immediately. This value is expected in ISO-8601 format and the maximum future time is 1 year. Note that if no time zone is provided, then it is assumed to be UTC. |
| DryRun | boolean Default: false Set to |
{- "From": "MessageCentre",
- "To": "44123456789",
- "Message": "This is a test message"
}{- "MessageIds": [
- 1234,
- 1235,
- 1236
], - "MessageGroupId": 123
}Cancel an SMS message that has been scheduled in future.
| MessageId required | integer Message Id sent in a response of the Send Sms API. If the message is a multi part message then any of the Ids returned will be accepted. |
{- "MessageId": 200000153
}{- "Message": "Message cancellation request accepted."
}These endpoints are available in the short term to ease the transition from the old Message Centre APIs to the new ones.
The request and response format of these APIs remain identical to the old APIs.
The endpoints listed below are accessible via the base URL https://legacy.msgcentre.com.
| USERNAME required | string Username for the client sending the message. |
| PASSWORD | string Password for the client sending the message. Must not be provided if a hashcheck is provided. |
| HASHCHECK | string Hash alternative to password for authentication. Must not be provided if a password is provided. |
| MESSAGETYPE required | string This is no longer used and must be provided as |
| DESTINATION required | string The destination mobile number in international format, for example |
| HEADER required | string Who the message should appear to be from. |
| SRCTON required | integer Type of number for the destination:
|
| BODY required | string The contents of the message to be sent. |
| SCHED | string The date and time the message should be sent. If this value is not provided or is in the past, the message will be sent immediately. This must be provided I as UTC in the format |
USERNAME=testUser&PASSWORD=testPassword&MESSAGETYPE=PLAIN&DESTINATION=44123456789&HEADER=Message%20Centre&SRCTON=1&Body=This%20is%20a%20test%20message
SUCCESS::12345 SUCCESS:12346
| USERNAME required | string Username for the client sending the message. |
| PASSWORD | string Password for the client sending the message. Must not be provided if a hashcheck is provided. |
| HASHCHECK | string Hash alternative to password for authentication. Must not be provided if a password is provided. |
| MESSAGETYPE required | string This is no longer used and must be provided as |
| DESTINATION required | string The destination mobile number in international format, for example |
| HEADER required | string Who the message should appear to be from. |
| SRCTON required | integer Type of number for the destination:
|
| BODY required | string The contents of the message to be sent. |
| SCHED | string The date and time the message should be sent. If this value is not provided or is in the past, the message will be sent immediately. This must be provided as UTC in the format |
| TEST | int Set to |
SUCCESS::12345 SUCCESS:12346
Mobile Originate (MO) SMS messages are inbound messages sent to either a predefined long number or short code by users.
MO messages are processed and forwarded to client APIs via a webhook.
Mobile Originate (MO) clients can set up their APIs to be used with this webhook.
An API call will be made for each SMS message received.
The API expects to receive a 2XX HTTP response code to indicate that the data was received successfully.
If the webhook does not receive a 2XX HTTP response code, it will attempt retries with an exponentially increasing delay up to 10 attempts, totalling approximately 1 hour.
| from | string The mobile number that sent the SMS. |
| to | string The long or short number that the SMS was sent to. |
| msg | string The content of the SMS message that was sent. |
| receivedtimestamp | string The timestamp for when the SMS message was received. DateTime formatted to |
| nwop | string Deprecated The network operator that the SMS was sent using. (Will always be empty due to deprecation). |
{- "from": "+1234567890",
- "to": "+0987654321",
- "msg": "Hello, this is a test message.",
- "receivedtimestamp": "2024-01-01T12:00:00.000Z",
- "nwop": ""
}The Delivery Receipt REST API triggers an API call whenever there is a status update for an MT message.
Mobile Terminated (MT) clients can set up their APIs to be used with this webhook.
An API call will be made for each delivery receipt received.
The API expects to receive a 2XX HTTP response code to indicate that the data was received successfully.
If the webhook does not receive a 2XX HTTP response code, it will attempt retries with an exponentially increasing delay up to 10 attempts, totaling approximately 1 hour.
Statuses that may be sent include:
| Status | Description |
|---|---|
| Unknown | Unknown Status |
| Sent | Message has been sent |
| Acknowledged | Received by the SMSC |
| Delivered | Message has been delivered |
| Failed | Message send failed |
| Cancelled | Sending of the message has been cancelled |
| Expired | Message expired |
| messageIds | Array of integers List of Message Ids for which the status report is provided.. |
| messageGroupId | integer A Message Group ID that identifies all parts of a multi-part message. |
| status | string The status of the message. |
| receivedTimeStamp | string The timestamp indicating when the status was received. DateTime formatted to |
{- "messageIds": [
- 123456,
- 123457
], - "messageGroupId": 213456,
- "status": "Delivered",
- "receivedTimeStamp": "2025-01-01T08:00:00.000Z"
}