FX Blue SMS library - User guide

The SMS Library is a simple DLL which any MT4 developer can use to add SMS alerts to their EA. The SMS is sent directly from MT4; delivery is faster and more reliable than using an email-to-SMS gateway.

1Overview and installation

1.1Overview of the MT4 SMS Library

The MT4 SMS Library allows MetaTrader 4 software developers to add SMS notifications to their EAs and indicators.

SMS transmission requires an account with an SMS provider: either Nexmo (www.nexmo.com) or Clickatell (www.clickatell.com).

1.2Installing the library

The installer which you download from the FX Blue website does a fully automated installation of the library. It puts all the required files into MT4's MQL4\Libraries directory, and adds example MQL4 code into the MQL4\Scripts directory.

1.3Licence

Unless otherwise specified in writing by FX Blue, this software is licensed for personal use only. You are not allowed to distribute it to other people, regardless of whether or not money is changing hands. You only have a licence to use the software if you, personally, downloaded it from our website.

The software is provided entirely at the user's risk, and you should check it thoroughly before deploying it on computers trading real money. FX Blue accepts no responsibility whatsoever for any loss of any kind caused by installation or use of the software.

2Opening an SMS account with Clickatell or Nexmo

You need an account with either Nexmo (www.nexmo.com) or Clickatell (www.clickatell.com).

Please note that the following details are subject to change if Nexmo or Clickatell alter the layout of their websites.

2.1Setting up a Nexmo account

In order to send SMS via Nexmo you need to register on their site at www.nexmo.com. You will need to provide an email address (a real one!) and a mobile phone number to receive a confirmation text. This phone number does not have to be the one which you subsequently want to send alerts to.

Once you have registered, the "Api Settings" section of the Nexmo Dashboard will show you an "API key" and "API secret" for sending texts via your account with them. You then use these values as the SMS_param1 and SMS_param2 values for the DLL calls.

2.1.1US and Canadian recipients

If you want to send to a US or Canadian phone number, one extra step may be required because of anti-spam regulations. You may need a "virtual number" to send from, which you enter as the SMS_param3 value for the DLL call. For further information, please see:

https://nexmo.zendesk.com/entries/22362928-Specific-Carrier-Restrictions-to-the-US-and-Canada-DIRECT-routes

2.2Setting up a Clickatell account

The procedure for setting up an account with Clickatell is a little complicated. The following steps could potentially change if Clickatell alter their website.

  • Create a "Clickatell Central" account at:
    https://www.clickatell.com/central/user/client/step1_new.php?prod_id=2.
  • Wait for the confirmation email to arrive, and then log in to your account at http://www.clickatell.com/login.php. Choose "Clickatell Central (API)" from the list of products.
  • Set up a connection by clicking on "Manage my products" and then choose "HTTP" from the "Add connection" list in the top-left of the page.
  • Give the connection any name you like, leave the other fields blank, and click on Submit.
  • The "Manage my products" page will refresh to show an "API code" for the connection (usually 7 digits).

You fill in your choice of username and password as the SMS_param1 and SMS_param2 values in the EA's configuration, and you fill in the "API code" as the SMS_param3 value.

2.3Testing the account details

You can test the account details using the Test SMS script. You simply run the script by double-clicking on it in MT4's Navigator list, and then fill in the parameters such as SMS_param1 as described below.

Parameter

Description

SMS_Carrier

See below

SMS_param1

See below

SMS_param2

See below

SMS_param3

See below

SMS_Recipients

One or more recipient phone numbers for the SMS, separated by commas. These should be in international format, e.g. 447879215460

TextToSend

The test message to send

TestAsynchronousSend

Determines whether to test synchronous or asynchronous transmission.

3Using the MT4 SMS Library

N.B. Any MQ4 code which uses the MT4 SMS Library needs to be able to call DLL files. The "Allow DLL imports" setting must be turned on, either in the properties for the individual EA/script or at global level in MT4's Tools/Options/Expert Advisors settings. Please note that the global setting does not affect any EAs which are already running; it is the default which is used when you next add an EA or script to a chart.

An example of using MT4 Email Library can be found in the "FX Blue - Test SMS.mq4" script. This demonstrates both synchronous and asynchronous transmission.

3.1Importing MT4SMSAlert.dll

The first step in using the library from MQ4 code is to import the DLL using a declaration such as the following:

#import "MT4SMSAlert.dll"
  int SendSMS_SynchronousW(int Carrier, string SMS_param1, string SMS_param2, string SMS_param3, 
                         string Recipient, string SMSText, int Flags);
  int SendSMS_AsynchronousW(int Carrier, string SMS_param1, string SMS_param2, string SMS_param3, 
                         string Recipient, string SMSText, int Flags);
  int CheckAsyncSMSResult(int Handle);
  int GetLastGatewayError2(uchar&[], int);
#import

3.2Sending SMS messages synchronously

You can send SMS synchronously using the SendSMS_SynchronousW() function. This does not return, and MQL4 execution does not continue, until delivery of the SMS has either succeeded or failed.

As a general rule, you can safely use synchronous transmission from an EA, but not from an indicator. If an indicator sends synchronous SMS, and there is a delay in connecting to the SMS provider, then the whole of the MT4 application can freeze while the communication is taking place.

The parameters for the SendSMS_SynchronousW() function are as follows:

Parameter

Nexmo account

Clickatell account

SMS_carrier

1

0

SMS_param1

Nexmo "API key"

The username you chose when registering with Clickatell

SMS_param2

Nexmo "API secret"

The password you chose when registering with Clickatell

SMS_param3

If sending to a US or Canadian number, this needs to be a "virtual number" which you register through Nexmo. For other recipients, this is the text which you want to appear as the sender of the SMS.

The "API code" assigned after creating the HTTP "connection" within your Clickatell account

SMS_Recipients

A list of recipient phone numbers for SMS alerts, separated by commas. These should be in international format, e.g. 447879215460

SMSText

The SMS text to send. Messages exceeding 160 characters will be split into multiple texts.

Flags

Reserved for future use. Set to zero.

The return value from the function is one of the success/error codes listed below.

3.3Sending SMS messages asynchronously

The parameters for using the SendSMS_AsynchronousW() function are the same as for sending a synchronous message.

However, instead of a success/error code, the function returns a "handle" which can then be used to track the progress of the request. If the handle is zero, then the SMS library was unable to start an asynchronous request.

Having started an asynchronous request, you can then check its status using the CheckAsyncSMSResult() function. This will return SMSERR_INPROGRESS (-1) while the request is still in progress, followed by one of the codes listed below.

Once the CheckAsyncSMSResult() function has returned a final status (i.e. any value other than SMSERR_INPROGRESS), the request is over and the handle is no longer valid for further calls to CheckAsyncSMSResult().

3.4Success/error codes

The following SMS functions can return the following success/error codes. An invalid username, password, or API code will usually lead to error 6.

Value

Name

Description

-1

SMSERR_INPROGRESS

Asynchronous request in progress. Only applicable to CheckAsyncSMSResult()

0

SMSERR_NOERROR

Synchronous/asynchronous request succeeded.

1

SMSERR_NOXMLHTTP

The Microsoft XML Parser is not installed on the computer

2

SMSERR_OPENFAILED

Failed to open a connection to the Clickatell servers

3

SMSERR_SENDFAILED

Failed to send data to the Clickatell servers

4

SMSERR_HTTPERROR

Unexpected error from the Clickatell servers

5

SMSERR_NORESPONSE

No response from the Clickatell servers. Message may or may not have been sent.

6

SMSERR_GATEWAYERROR

Request declined by the Clickatell servers, usually because of invalid credentials or lack of credit.

7

SMSERR_GENERALERROR

General unexpected error.

9999

SMSERR_HANDLEINVALID

Handle is no longer valid for a call to CheckAsyncSMSResult()

3.4.1Getting further error information from the SMS provider

If message transmission results in error 6, you may be able to get further error information from the SMS provider using the GetLastGatewayError2() function.

This is called by providing it with a buffer, and then converting that buffer into text. For example:

   uchar Buffer[];
   int szBufferSize = 10000;
   ArrayResize(Buffer, szBufferSize);
   int resGLG = GetLastGatewayError2(Buffer, szBufferSize);
   if (resGLG > 0) {
      string strGatewayError = CharArrayToString(Buffer, 0, resGLG);
   } else {
      // Buffer not large enough, or no response from carrier
   }
 
Continue to site >