This tutorial will guide you step by step in creating a simple PHP application that will send SMS containing "Hello World" text.

I. Prerequisites

Before developing the application, you should fulfill a few prerequisites, as follows:

1. Your application server should have internet connection, since Creatary platform resides within the internet cloud. The application server should also have a reachable public IP address in order to receive the OAuth callback or incoming message (SMS) from Creatary.
2. Because we will make a PHP application, your application server should have PHP capable web server installed. You may install it manually or use the installer from XAMPP which has already had Apache, PHP, and MySQL in one package.
3. You should have a Creatary account as developer by registering through our web site. You may need an invitation code to make this account. Please click here to request for one.
4. Download the sources needed for this tutorial from here. For this tutorial, we use "oauth-php" library as the OAuth client. Please go to this site to download the library.

II. Intro to OAuth

All of Creatary APIs use OAuth as the standard authentication method. We use OAuth because it is a secure and open protocol widely used for Authentication and Authorization. It enables the application to access Subscriber's protected resources without requiring to disclose the Subscriber credentials (e.g.: mobile number) to the application.

Simplified OAuth Flow:

1. Register your application to get CONSUMER KEY and CONSUMER SECRET.
2. Obtain Request Token for your application using the CONSUMER key.
3. Get User Authorization using Request Token.
4. Obtain Access Token for your application.
5. Use Access Token to access our APIs.

For complete flow of OAuth process, please refer to "OAuth Authorization Flow".

Finally before going through the steps make sure you have already registered as a developer at Creatary website. Please click here if you haven't done so.

III. Let's Make The Application

Ok, now that you have everything ready, please follow the steps below to start creating your first application using our SMS API:

1. 1. Register your application to obtain Consumer Key and Consumer Secret

   Go to this link: https://telcoassetmarketplace.com/developer/applications/addedit. Then fill in the "Main Details" and "Application Callbacks" sections. You can use the following screenshots as your reference.
   
   

   Once you clicked on the "Create" button, you should get your Consumer Key and Consumer Secret for your application.

   

2. 2. Set Up Variables for Your Application

   This step will show you how to setup some variables that will be used by this tutorial application. The following are the variables that you should modify according to your application specifications.

   sms-hello-world/include/defines.php

   define("APP_HOST", "http://yoursite.com");
   define("APP_URL", APP_HOST . "");
   define("APP_CALLBACK_URL", APP_URL . "/callback.php");
   define("CREATARY_CONSUMER_KEY", "s39qwljl03bcljtp");
   define("CREATARY_CONSUMER_SECRET", "kqmspi404sypdcyr");

   • CREATARY_CONSUMER_KEY: This is the consumer key you get after registering your application.
   • CREATARY_CONSUMER_SECRET: This is the consumer secret you get after registering your application.

3. 3. Obtain Request Token

   In this step we will show you how to obtain request token for your application. To request a Request Token you will need to provide your application Consumer Key. Moreover, this should have been defined before in the previous step.

   sms-hello-world/sendSMS.php

   Common::requestRequestToken($usrId, APP_CALLBACK_URL);

   • $usrId: Required parameter that will associate user (subscriber) with OAuth token.
   • APP_CALLBACK_URL: Optional parameter to override configured application callback url.

4. 4. Get User Authorization

   Next is to get user authorization from the user of your application. You MUST get user authorization first before being able to access our APIs. The following snippet show you how to redirect your user to Creatary website to ask his/her authorization to access his/her private data.

   Normally a subscriber (user of your application) should see the following screen after they have logged in to Creatary website using his/her mobile phone number:

   

   However, you can also test your application using your Persona by signing in using your developer account and selecting one of your Personas:

   

5. 5. Obtain Access Token

   Once you have get authorization from the user, your application now can obtain the Access Token for API access.

   sms-hello-world/sendSMS.php

   Common::requestAccessToken($usrId, $oauthToken, $oauthVerifier);

   • $usrId: Required parameter that will associate user (subscriber) with OAuth token.
   • $oauthToken: The request token obtained from previous step.
   • $oauthVerifier: The oauthVerifier obtained from previous step to verify the request token.

6. 6. Use Obtained Access Token to Access Creatary API

   Finally you can now use the stored Access Token to use our API to send a "Hello World" SMS to the user. Each user ($usrId) will always be associated with one access token.

   sms-hello-world/sendSMS.php

   $jsonResponse = SMSApi::sendSMS($usrId, 'Hello World SMS');
               
   if (is_null($jsonResponse) || $jsonResponse->status->code != 0) 
   {
      echo 'Error occured while sending SMS: ' . $jsonResponse->status->message;
   } 
   else 
   {
      echo 'SMS successfully sent';
   }

IV. Start testing your Application using Sandbox

The sandbox is the place where you can test your applications without the need of interacting with real subscribers. In the sandbox, personas are the virtual representation of subscribers and you can interact with them in many different ways (sending a persona an SMS, receiving an SMS from a persona, performing a charge request on a persona's balance, recharging a persona's balance, finding the location of a persona and setting the location of a persona).

To generate your persona please click on the "sandbox" top menu of Creatary website, then click on the "generate new persona" button.

The Hello World tutorial application is a very simple example. It will send the “Hello World” SMS to the subscriber. We will test this application using Creatary Sandbox.

1. Make sure the application has been registered within your developer account.
2. Check whether all required parameters have correctly set. (e.g. consumer key, consumer secret, callback URL, application URL).
3. Make sure you have created a persona on your developer account
4. Open a new browser and hit this URL to test

http://[your_server_ip]:[port]/sms-hello-world/sendSMS.php

5. You will be directed to Creatary login page. Make sure to insert your developer account and password. Then an authorization page will appeare

6. Just click the "authorize" button to give the permission to the application.
7. Your "Hello World" application will send an SMS to Creatary using the given access token. To check this, please go to Creatary Sandbox page.
8. You will notice on the persona logs that an SMS MT has been sent to the persona.