Sending a Message
Sending a Message
We ❤ PHP
At MessageCloud, we love PHP. So much so that we have a prebuilt library available for you to use on our GitHub repository. It makes the integration a cinch!
Sending an SMS to MessageCloud is simple. Whether you are sending a free message, replying to an MO message you've received, or sending a scheduled subscription message, the following page is applicable to you.
API Endpoint
We recommend that you use the HTTPS endpoint when sending requests to our API. This will ensure all communications between your server and our API endpoint are encrypted. If you'd prefer not to use the secure version, the non-HTTPS version is also available.
https://client.txtnation.com/gateway.php
The HTTP GET variables you need to use to send us a message are:
Variable | Type | Contents |
---|---|---|
|
String |
The MSISDN to which you are sending the message. This should be in full international format without leading zeros or + sign. Note, in some countries (France is a good example) this value may be an alias for the real MSISDN and may have a preceding non-numeric character, for example, #288166360171234. In cases like this, you should reply to the alias including any non-numeric prefix. |
|
String |
The contents of the message you want to send. Your message body can be up to 160 characters when using the GSM character set. Please ensure the value of To send any other characters you can set |
|
String |
The sender ID field. If the message you are sending is free then you may set who the message will appear to have come from. This field can be up to 11 characters in length. Premium SMS always appear to come from the billing shortcode and can not be changed using this field. |
|
String |
Your brand or company code. Your company code must be passed across in each message you send along with your |
|
String |
This is your encrypted key as found in your MyMessageCloud control panel. This field is case sensitive. |
|
Integer |
In an MO billed country you must use If part of a subscription you must set all messages to If you are sending a free message then you can set this field to |
|
String |
The unique message identifier. This is used in conjunction with the If you are using If you are using |
|
String |
The originating network of the message or, in the case of free messages, the network to which you will be sending. For sending a free message you can set this field to If you are replying to a message you've received, this field must be the same as the |
|
String |
The local currency you are billing in, in its 3 digit ISO 4217 representation. For example Please note if the currency you pass does not match that of the country you are attempting to send an SMS our system will bill the closest tariff available. It is recommended that you pay close attention to our supported tariffs if you are billing in multiple countries. |
|
Float |
The cost of the message you are sending. For best results, the value can contain up to two decimal places. Example 2.00 This is the amount you wish to charge the consumer for receiving the message and is used in conjunction with the |
Finally, there are some optional parameters that can be used to change the behaviour of the sent message through our platform.
Variable | Type | Contents |
---|---|---|
|
Integer |
After the consumer has opted out of your service (see Stop Requests) you may be able to send a free message to them to confirm their opt-out. Please contact the support team to find out more about using |
|
String |
If you want to encode your message as a particular character set before it is sent to the consumer then you may use the |
Server Responses
We strongly recommend that you store all Gateway responses to help debug any errors and to improve your ability to audit your requests.
When your correctly formatted posts hit our server we will respond with SUCCESS
. This simply means the gateway will attempt to deliver your message, it does not indicate a successful delivery. You should use delivery reports to confirm the status of the message.
If your message was not accepted by the Gateway one of the following errors will be returned:
Error code | Description |
---|---|
|
Duplicate reply for |
|
A binary transaction has been requested but UDH has not been specified. |
|
An invalid |
|
Unable to find inbound record for |
|
Internal server error. |
|
Operator Error. |
|
Tariff Error. Please check the |
|
Invalid Request Data. |
|
Invalid Operator ID. |
|
Invalid Test. Please review your settings. |
|
Sending failed as you have no credits remaining on your account. |
|
Sending through your account is currently disabled in this country. |
|
The message submitted to Gateway could not be decoded as UTF-8. |
|
This error occurs when you have no credits remaining to send a free message. |
BARRED |
Sending failed as the number has sent stop to the shortcode. |
|
The |
|
A non-numeric value has been set in the |
|
Missing |
|
The |
|
Missing |
|
The |
|
The |
|
The |
|
An invalid |
|
The |
|
The |
|
The |
|
Sending premium messages to MO-billed networks is not available. |
|
Sending premium messages to free networks is not available. |
|
The |
Code Examples
Sample
The below snippet shows a request to our API via cURL and includes all the headers you can expect to see on both the request and response.
$ curl -v "https://client.txtnation.com/gateway.php?cc=marc&ekey=2a814af3004d7ec7063fe8e2aac00eca&message=Hello%2C%20world%21&number=447445566731" * Trying 10.15.18.3... * TCP_NODELAY set * Connected to client.txtnation.com (10.15.18.3) port 443 (#0) * TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 * Server certificate: *.txtnation.com * Server certificate: RapidSSL SHA256 CA * Server certificate: GeoTrust Global CA > GET /gateway.php?cc=marc&ekey=2a814af3004d7ec7063fe8e2aac00eca&message=Hello%2C%20world%21&number=447445566731 HTTP/1.1 > Host: client.txtnation.com > User-Agent: curl/7.54.0 > Accept: */* > < HTTP/1.1 200 OK < X-Served-By: Eos < Set-Cookie: PHPSESSID=rc555agtqvgil8676l3ounoo17; path=/ < Expires: Thu, 19 Nov 1981 08:52:00 GMT < Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0 < Pragma: no-cache < Content-length: 7 < Content-type: text/html; charset=UTF-8 < Date: Fri, 03 Nov 2017 10:05:30 GMT < Server: txtNation HTTP Server < * Connection #0 to host client.txtnation.com left intact SUCCESS