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.

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:

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.

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
   }