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

number

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.

message

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 message is sent to us in URL-encoded UTF-8. For example, the Euro currency symbol — € — can be sent to us as %E2%82%AC.

To send any other characters you can set encoding=utf-8. For any other special character sending requirements please contact our support team.

title

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.

cc

String

Your brand or company code. Your company code must be passed across in each message you send along with your ekey to authenticate you with our gateway. Your company code is displayed in the top-right hand corner of the MyMessageCloud control panel next to your username.

ekey

String

This is your encrypted key as found in your MyMessageCloud control panel. This field is case sensitive.

reply

Integer

1 or 0. If set to 1 you are telling MessageCloud that the post is in reply to a specific message ID (see id below). This will pair the incoming message and your reply together in the MyMessageCloud control panel and in some countries a linked transaction is required to complete the billing. If your service involves only a single reply per request it is advised that you use this variable. Only one reply can be sent per unique message ID.

In an MO billed country you must use  reply=1 and the corresponding ID in order to complete the payment.

If part of a subscription you must set all messages to reply=0

If you are sending a free message then you can set this field to 0.

id

String

The unique message identifier. This is used in conjunction with the reply variable (above).

If you are using reply=1 then this field should be set to the value of the id variable we post to you in Receiving a Message.

If you are using reply=0 then you are free to assign the message ID yourself. This same ID will be posted back to you in the delivery report so you can track the status of your messages.

network

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 INTERNATIONAL but this feature will only work for free messages.

If you are replying to a message you've received, this field must be the same as the network variable we posted to you in Receiving a Message.

currency

String

The local currency you are billing in, in its 3 digit ISO 4217 representation. For example USD, EUR, EUR, GBP. You can use any currency when sending a free message.

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.

value

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 currency variable. This value must be equal to an available tariff in the country you are sending the SMS or 0 in the case of a free message.

Finally, there are some optional parameters that can be used to change the behaviour of the sent message through our platform.

Variable Type Contents

smscat

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 smscat for this feature.

encoding

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 encoding parameter to achieve this. Typically, this feature is network-dependent but many support utf-8. Please note that the maximum possible length of your message parameter will reduce when using this feature.

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

IR-101

Duplicate reply for id. We have already received a reply message for this id.

IR-102

A binary transaction has been requested but UDH has not been specified.

IR-103

An invalid ekey / cc has been sent.

IR-104

Unable to find inbound record for id. Please check the id and network you submitted matches the values we sent to you in the MO.

E-100

Internal server error.

E-101

Operator Error.

E-102

Tariff Error. Please check the value field and make sure it's formatted correctly.

E-103

Invalid Request Data.

E-105

Invalid Operator ID.

E-107

Invalid Test. Please review your settings.

E-108

Sending failed as you have no credits remaining on your account.

E-109

Sending through your account is currently disabled in this country.

E-110

The message submitted to Gateway could not be decoded as UTF-8.

NO CREDITS

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.

IR-401

The reply variable has not been used correctly.

IR-403

A non-numeric value has been set in the id parameter.

IR-404

Missing number parameter in the HTTP request.

IR-405

The number field was not numeric. All phone numbers must be numeric except in special circumstances.

IR-409

Missing value parameter in the HTTP request.

IR-410

The value parameter was non-numeric.

IR-412

The network / value parameters do not match an existing price point.

IR-413

The value parameter must be 0.00 or above.

IR-414

An invalid cc was used.

IR-415

The cc parameter used in the HTTP request was not found in our system.

IR-416

The message parameter was not found in the HTTP request.

IR-417

The message parameter was too long.

IR-418

Sending premium messages to MO-billed networks is not available.

IR-419

Sending premium messages to free networks is not available.

IR-420

The network parameter sent in the HTTP request was not found in our system.

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

Next: Receiving a Delivery Report