FortyTwo Message PHP SDK API (Version 0.0.1)

Fortytwo offers numerous ways for you to connect your applications to our Advanced Messaging Platform, allowing your systems to seamlessly communicate with your customers anywhere in the world.

For more information technical information go to our API Section »

Sign up for a FREE ACCOUNT

To try out our IM/SMS Messaging system you have to Register for a FREE Test Account.

icon_cash

Free test

credit

Start your trial with free test credit and get full benefits from our platform.

icon_network

1,000+

networks

Over 1,000 networks to reach your target worldwide.

icon_gear

24/7

live support

Our group of multilingual live support agents can help you anytime along the way.

Requirements

Setup & Installation

REST Service Endpoint

Host URL: https://rest.fortytwo.com/

Service Endpoint: /1/im

Content-Type: application/json; charset=utf-8

Verb (HTTP Method): POST

Sending SMS

The SMS REST interface is an application hosted on a server that listens for HTTP requests containing SMS message data encoded in JSON. It processes the HTTP requests and their associated SMS message data and sends the required SMS messages for onward delivery. The SMS REST interface sends back a JSON response containing information about the submitted SMS messages such as the message identifiers of the sent SMS messages.

The SMS REST interface also includes a callback application which sends back delivery reports. The callback application achieves this by sending HTTP callback requests to your HTTP server (which must return an appropriate response) in order for delivery reports to be received. The figure below illustrates the architectural setup.

 

SMS REST API

SMS REST API Diagram

SMS REST API CALLBACK

SMS REST API Callback Diagram

Send SMS to one Mobile Number

Use the method called sendSMS() to send a very simple SMS to a mobile phone.

Example File: /examples/send_sms.php

The parameters for this method are:

  • Mobile Phone Number with prefix
  • Content for SMS Message
  • (Optional: SenderID)
  • (Optional: Route)
PHP Code Sample:
  1. #Send an SMS to one mobile phone number
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $return = $message->sendSMS('INSERT_MOBILE_HERE','INSERT_CONTENT_HERE');
  5. //Handle the Return
  6. var_dump($return);

Send SMS to multiple Mobile Number

Use the method called sendMultipleSMS() to send a very simple SMS to multiple mobile phone.

Example File: /examples/send_multiple_sms.php

The parameters for this method are:

  • Array of Mobile Phone Numbers with prefix
  • Content for SMS Message
  • (Optional: SenderID)
  • (Optional: Route)
PHP Code Sample:
  1. #Send SMS to Multiple Phone Numbers
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $arrayNumbers = array('INSERT_MOBILE_HERE','INSERT_MOBILE_HERE');
  5. $return = $message->sendMultipleSMS($arrayNumbers,'INSERT_CONTENT_HERE');
  6. //Handle the Return
  7. var_dump($return);

Send Complex SMS

Use the method called sendComplexSMS() to send a very a complex SMS (used for customisations).

Example File: /examples/send_complex_sms.php

The parameters for this method are:

  • Object of type Destination (incl. all its needed properties)
  • Object of type SMSContent (incl. all its needed properties)
PHP Code Sample:
  1. #Send Complex SMS
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $message->setTTL(500);
  5. $destination1 = new Destination('INSERT_MOBILE_NUMBER_1');
  6. $destination2 = new Destination('INSERT_MOBILE_NUMBER_2');
  7. $destinationArray = array($destination1,$destination2);
  8. $SMSContent = new SMSContent('INSERT_CONTENT_HERE');
  9. $SMSContent->setSenderId('INSERT_SENDER_ID');
  10. $return = $message->sendComplexSMS($destinationArray,$SMSContent);
  11. //Handle the Return
  12. var_dump($return);

Sending IM via VIBER

The IM REST interface is an application hosted on a server that listens for HTTP requests containing IM message data and/or SMS message data encoded in JSON. It processes the HTTP requests and their associated IM and/or SMS message data, performs some routing logic, and sends the required messages for onward delivery. The IM REST interface sends back a JSON response containing information about the submitted IM and/or SMS messages such as the message identifiers of the sent messages.

The IM REST interface allows undelivered IM messages to automatically fallback to the use of the SMS gateway if so desired.

The IM REST interface also includes a callback application which sends back delivery reports. The callback application achieves this by sending HTTP callback requests to your HTTP server (which must return an appropriate response) in order for delivery reports to be received. The figure below illustrates the architectural setup.

IM REST API

SMS REST API Diagram

IM REST API CALLBACK

SMS REST API Callback Diagram

Send IM via VIBER to one Mobile Number

Use the method called sendIM() to send an Instant Message via VIBER to a mobile phone.

Example File: /examples/send_im.php

The parameters for this method are:

  • Mobile Phone Number with prefix (must have VIBER installed)
  • Content for IM Message
PHP Code Sample:
  1. #Send IM Message to one Phone Number
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $return = $message->sendIM('INSERT_MOBILE_HERE','INSERT_CONTENT_HERE');
  5. //Handle the Return
  6. var_dump($return);

Send IM via VIBER to multiple Mobile Number

Use the method called sendMultipleIM() to send Instant Messages via VIBER to a range of mobile phones.

Example File: /examples/send_multiple_im.php

The parameters for this method are:

  • Array of Mobile Phone Number with prefix (must have VIBER installed)
  • Content for IM Message
PHP Code Sample:
  1. #Send IM Message to multiple Phone numbers
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $arrayNumbers = array('INSERT_MOBILE_HERE','INSERT_MOBILE_HERE');
  5. $return = $message->sendMultipleIM($arrayNumbers,'INSERT_CONTENT_HERE');
  6. //Handle the Return
  7. var_dump($return);

Send Complex IM via VIBER

Use the method called sendComplexIM() to send a very a complex IM (used for customisations).

Example File: /examples/send_complex_im.php

The parameters for this method are:

  • Object of type Destination (incl. all its needed properties)
  • Object of type IMContent (incl. all its needed properties)
PHP Code Sample:
  1. #Send Complex IM
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $destination1 = new Destination('INSERT_MOBILE_NUMBER_1');
  5. $destination2 = new Destination('INSERT_MOBILE_NUMBER_2');
  6. $destinationArray = array($destination1,$destination2);
  7. $imContent = new IMContent('INSERT_IM_CONTENT_HERE');
  8. $return = $message->sendComplexIM($destinationArray,$imContent);
  9. //Handle the Return
  10. var_dump($return);

Sending IM or SMS (depending on Message plan selected)

The developer can opt to send the message via SMS (if cheaper) rather than via IM. (Prices can be checked from the prices page in the "FortyTwo IM Control Panel").

The Token generated can also be set to have the current "Message Plan" selected automatically by adjusting it in the Control Panel. The Message Plan routing can also be overriden with the $cheapestFirst parameter (If this is set to 'TRUE' and SMS is cheaper than IM, then SMS would be used)

In some cases, the destination mobile phone might not have the IM platform (e.g Viber) installed, in this case the developer can opt to do a fallback mechanism to send an SMS in case this happens. The IM message might fallback to SMS if

  • The Phone does not have a VIBER account
  • The Phone might have VIBER installed but does not recieve any messages for whatever reason and the TTL (time to live) have expired.

Send an Instant Message or SMS to one destination

Use the method called sendInstantMessageOrSms() to send Instant Messages or SMS depending on the selected Message Plan.

Example File: /examples/send_im_or_sms.php

The parameters for this method are:

  • Mobile Phone Number with prefix
  • Content for IM Message
  • Content for SMS Message
  • (Optional: cheapestFirst [default:FALSE] - If this is set to 'TRUE' and SMS is cheaper than IM, then SMS would be used)
  • (Optional: SenderID)
  • (Optional: Route)
PHP Code Sample:
  1. #Send an Instant Message or SMS to one destination
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $return = $message->sendInstantMessageOrSMS('INSERT_MOBILE_HERE','INSERT_IM_CONTENT_HERE','INSERT_SMS_CONTENT_HERE');
  5. //Handle the Return
  6. var_dump($return);

Send an Instant Message or SMS to multiple destinations

Use the method called sendMultipleInstantMessageOrSms() to send multiple Instant Messages or SMS depending on the selected Message Plan.

Example File: /examples/send_multiple_im_or_sms.php

The parameters for this method are:

  • Array of Mobile Phone Number with prefix
  • Content for IM Message
  • Content for SMS Message
  • (Optional: cheapestFirst [default:FALSE] - If this is set to 'TRUE' and SMS is cheaper than IM, then SMS would be used)
  • (Optional: SenderID)
  • (Optional: Route)
  1. #Send an Instant Message or SMS to multiple destinations
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. $arrayNumbers = array('INSERT_MOBILE_HERE','INSERT_MOBILE_HERE');
  5. $return = $message->sendMultipleInstantMessageOrSMS($arrayNumbers,'INSERT_IM_CONTENT_HERE','INSERT_SMS_CONTENT_HERE');
  6. //Handle the Return
  7. var_dump($return);

Send Complex Instant Message or SMS

Use the method called sendComplexInstantMessageOrSms() to send custom Instant Messages or SMS depending on the selected Message Plan.

Example File: /examples/send_complex_im_or_sms.php

The parameters for this method are:

  • Object of type Destination (incl. all its needed properties)
  • Object of type IMContent (incl. all its needed properties)
  • Object of type SMSContent (incl. all its needed properties)
  • (Optional: cheapestFirst [default:FALSE] - If this is set to 'TRUE' and SMS is cheaper than IM, then SMS would be used)
PHP Code Sample:
  1. #Send Complex Instant Message or SMS (taking LOW_COST as a message plan)
  2. require_once('../src/fortytwo/FortytwoMessage.php');
  3. $message = new FortytwoMessage('INSERT_TOKEN_HERE');
  4. #Add multiple Destinations - Start
  5. $destination1 = new Destination('INSERT_MOBILE_HERE');
  6. $destination2 = new Destination('INSERT_MOBILE_HERE');
  7. $destinationArray = array($destination1,$destination2);
  8. #Add multiple Destinations - End
  9. $imContent = new IMContent('INSERT_IM_CONTENT');
  10. $SMSContent = new SMSContent('INSERT_SMS_CONTENT');
  11. $SMSContent->setSenderId('INSERT_SENDER_ID');
  12. $return = $message->sendComplexInstantMessageOrSMS($destinationArray,$imContent,$SMSContent,true);
  13. //Handle the Return
  14. var_dump($return);

Custom API Calls

Developers can also opt for building their own JSON Object and sending it to the REST API Server directly.

Post custom JSON Data to REST API

In the event that the developer wants to build his own JSON Object rather than using the simplified methods supplied above, the postData() method can be used.

Example File: /examples/json_post.php

The parameters for this method are:

PHP Code Sample:
  1. #Send a JSON Object to REST API Server
  2. #Check Documentation on how to generate a JSON Object
  3. require_once('src/fortytwo/FortytwoMessage.php');
  4. $messageObject = new FortytwoMessage('INSERT_TOKEN_HERE');
  5. $response = $messageObject->postData('{
  6. "destinations": [
  7. {
  8. "number": "INSERT_MOBILE_NUMBER"
  9. }
  10. ],
  11. "sms_content": {
  12. "message": "INSERT_SMS_CONTENT",
  13. "sender_id": "INSERT_SENDER_ID"
  14. }
  15. }');
  16. var_dump($response);

API Response & Validation

This PHP Library acts a bridge to Fortytwo REST API server, thus any data validation is handled through the REST API itself.

The request itself will return an JSON Object (String) with all the relevant information (e.g Invalid Token) and its up to the Developer on how they want to handle/display this information in their system.

If the response returned with HTTP Status Code set to "200", then the request was successful, any other status means that there was an error.

Read more about Responses »

Sample Validation JSON Response for Errors:

If the request had validation errors the API will return a JSON object as shown below:

  1. {
  2. "api_job_id": "54a84753-492b-438a-9e08-15fad2057710",
  3. "result_info": {
  4. "status_code": 403,
  5. "description": "Forbidden: Validation error/s has/have occured, Reason/s: DestinationInfo has an invalid [number]
  6. value. Value [avc] does not match pattern [^[1-9][0-9]{6,14}$]. DestinationInfo fields were: MSISDN[number]:[avc];
  7. CUSTOM_ID[custom_id]:[null]; TEXT_PARAMS[params]:[null]"
  8. },
  9. "results": {}
  10. }

Sample Validation JSON Response for Success

If the request was successful the API will return a JSON object as shown below:

  1. {
  2. "api_job_id":"6b6b843c-542225a-4118-8d6c-26ac61009efc",
  3. "result_info":{
  4. "status_code":200,
  5. "description":"Request successful (no errors occured and the message has been submitted)"
  6. },
  7. "results":{
  8. "35690556699":{
  9. "message_id":"14416294250660014003",
  10. "custom_id":""
  11. }
  12. }
  13. }