Objective-C code samples for integration with LabsMobile's SMS API

Below are the examples of programming code in Objective-C language to send SMS messages through the LabsMobile platform API.

This documentation is designed for you to connect your applications with the LabsMobile platform and automate the sending of SMS messages. The main objective of the integration of these applications is the sending of SMS messages and related communications.

Advice We recommend using our API SMS http/POST in JSON format for any integration with the LabsMobile platform. But we have other API versions that you can use depending on your environment and requirements.

With these examples you will be able to perform the integration of the following functionalities:

Send SMS messages individually or in bulk.
Check your account balance.
Receive delivery confirmation and/or error notifications corresponding to the messages sent.
Obtain notification and data of the messages received in the virtual numbers contracted.

To be taken into account

The LabsMobile API SMS uses a common base URL for all requests: https://api.labsmobile.com.

It is highly recommended to use a URL that includes the HTTPS protocol in any version of the API.

Authentication is done with the username and an API token, myUsername:myToken. You must create the API token from the API Settings section of your account.

Send SMS with http/POST

Here is a code example in Objective-C language to send SMS messages using the API SMS http/POST that uses the JSON format for the information exchange variables.

As you can see, you need to create a structure in JSON format containing all the necessary parameters for sending and make a HTTP/POST call with this data in the body of the request.

#import <Foundation/Foundation.h>
int main(int argc, const char * argv[]) {
   @autoreleasepool {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
      

       NSString *username = @"myUsername";
       NSString *token = @"myToken";
      
       NSString *authString = [NSString stringWithFormat:@"%@:%@", username, token];
       NSData *authData = [authString dataUsingEncoding:NSUTF8StringEncoding];
       NSString *base64AuthString = [authData base64EncodedStringWithOptions:0];
      
       NSDictionary *headers = @{
           @"Content-Type": @"application/json",
           @"Authorization": [NSString stringWithFormat:@"Basic %@", base64AuthString]
       };
      
       NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.labsmobile.com/json/send"]
                                                                 cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                             timeoutInterval:10.0];
       [request setAllHTTPHeaderFields:headers];
       NSData *postData = [[NSData alloc] initWithData:[@"{\r\n \"message\":\"Your verification code is 123\",\r\n  \"tpoa\":\"Sender\",\r\n  \"recipient\":\r\n    [\r\n      {\r\n        \"msisdn\":\"12015550123\"\r\n      }\r\n    ]\r\n}\r\n\r\n" dataUsingEncoding:NSUTF8StringEncoding]];
       [request setHTTPBody:postData];
       [request setHTTPMethod:@"POST"];
      
       NSURLSession *session = [NSURLSession sharedSession];
       NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                   completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
           if (error) {
               NSLog(@"%@", error);
               dispatch_semaphore_signal(sema);
           } else {
               NSError *parseError = nil;
               NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
               NSLog(@"%@",responseDictionary);
               dispatch_semaphore_signal(sema);
           }
       }];
       [dataTask resume];
       dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
   }
}

#import <Foundation/Foundation.h>
int main(int argc, const char * argv[]) {
   @autoreleasepool {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
      

       NSString *username = @"myUSername";
       NSString *token = @"myToken";
      
       NSString *authString = [NSString stringWithFormat:@"%@:%@", username, token];
       NSData *authData = [authString dataUsingEncoding:NSUTF8StringEncoding];
       NSString *base64AuthString = [authData base64EncodedStringWithOptions:0];
      
       NSDictionary *headers = @{
           @"Content-Type": @"application/json",
           @"Authorization": [NSString stringWithFormat:@"Basic %@", base64AuthString]
       };
      
       NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.labsmobile.com/json/send"]
                                                                 cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                             timeoutInterval:10.0];
       [request setAllHTTPHeaderFields:headers];
       NSData *postData = [[NSData alloc] initWithData:[@"{\r\n  \"message\":\"Don't miss our Sale! Use code XXXX123 for 20% off.\",\r\n  \"tpoa\":\"Sender\",\r\n  \"recipient\":\r\n    [\r\n      {\r\n        \"msisdn\":\"12015550123\"\r\n      },\r\n      {\r\n        \"msisdn\":\"12015550124\"\r\n      },\r\n      {\r\n        \"msisdn\":\"12015550125\"\r\n      }\r\n    ]\r\n}\r\n"  dataUsingEncoding:NSUTF8StringEncoding]];
       [request setHTTPBody:postData];
       [request setHTTPMethod:@"POST"];
      
       NSURLSession *session = [NSURLSession sharedSession];
       NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                   completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
           if (error) {
               NSLog(@"%@", error);
               dispatch_semaphore_signal(sema);
           } else {
               NSError *parseError = nil;
               NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
               NSLog(@"%@",responseDictionary);
               dispatch_semaphore_signal(sema);
           }
       }];
       [dataTask resume];
       dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
   }
}

{
  "subid": "65f33a88ceb3d",
  "code": "0",
  "message": "Message has been successfully sent."
}

{
  "subid": "65f7f7041385d",
  "code": "35",
  "message": "The account has no enough credit for this sending"
}

All error codes can be found in API documentation, error codes.

For more details on the available parameters and configuration options, see the official documentation at:

SMS http/POST API Documentation

Send SMS with http/GET

This is an example of code in Objective-C language to send SMS messages using the SMS API http/GET.

As you can see, you must pass a series of GET variables in the same URL and make a HTTP call. It is important to encode all values as URL using the stringByAddingPercentEncodingWithAllowedCharacters function.

Important The SMS http/GET API transmits credentials (username and API token) unencrypted and unsecured. We recommend using this API GET only when absolutely essential and use the API SMS http/POST instead.

#import <Foundation/Foundation.h>
int main(int argc, const char * argv[]) {
   @autoreleasepool {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
      

       NSString *username = @"myUsername";
       NSString *token = @"myToken";
       NSString *message = @"Your verification code is 123";
       NSArray *msisdns = @[@"12015550123"];

      NSString *encodedUsername = [username stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
      NSString *encodedToken = [token stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
      NSString *encodedMessage = [message stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
      NSString *encodedMsisdns = [[msisdns componentsJoinedByString:@","] stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];

      
      
       NSString *urlString = [NSString stringWithFormat:@"https://api.labsmobile.com/get/send.php?username=%@&password=%@&msisdn=%@&message=%@", encodedUsername, encodedToken, encodedMsisdns, encodedMessage];

     
       NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:urlString]
                 cachePolicy:NSURLRequestUseProtocolCachePolicy
                 timeoutInterval:10.0];

       [request setHTTPMethod:@"GET"];
      
       NSURLSession *session = [NSURLSession sharedSession];
       NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                   completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
           if (error) {
               NSLog(@"%@", error);
               dispatch_semaphore_signal(sema);
           } else {
               NSString *xmlString = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
               NSLog(@"%@", xmlString);
               dispatch_semaphore_signal(sema);
           }
       }];
       [dataTask resume];
       dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
   }
}

#import <Foundation/Foundation.h>
int main(int argc, const char * argv[]) {
   @autoreleasepool {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
      

       NSString *username = @"myUsername";
       NSString *token = @"myToken";
       NSString *message = @"Don't miss our Sale! Use code XXXX123 for 20% off.";
       NSArray *msisdns = @[@"12015550123",@"12015550124",@"12015550125"];
      
       NSString *encodedUsername = [username stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
       NSString *encodedToken = [token stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
       NSString *encodedMessage = [message stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];
       NSString *encodedMsisdns = [[msisdns componentsJoinedByString:@","] stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLQueryAllowedCharacterSet]];

      
       NSString *urlString = [NSString stringWithFormat:@"https://api.labsmobile.com/get/send.php?username=%@&password=%@&msisdn=%@&message=%@", encodedUsername, encodedToken, encodedMsisdns, encodedMessage];

     
       NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:urlString]
                 cachePolicy:NSURLRequestUseProtocolCachePolicy
                 timeoutInterval:10.0];

       [request setHTTPMethod:@"GET"];
      
       NSURLSession *session = [NSURLSession sharedSession];
       NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                   completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
           if (error) {
               NSLog(@"%@", error);
               dispatch_semaphore_signal(sema);
           } else {
               NSString *xmlString = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
               NSLog(@"%@", xmlString);
               dispatch_semaphore_signal(sema);
           }
       }];
       [dataTask resume];
       dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
   }
}

{
  "subid": "65f33a88ceb3d",
  "code": "0",
  "message": "Message has been successfully sent."
}

{
  "subid": "65f7f7041385d",
  "code": "35",
  "message": "The account has no enough credit for this sending"
}

All error codes can be found in API documentation, error codes.

For more details on the available parameters and configuration options, see the official documentation at:

SMS http/GET API Documentation

Account balance inquiry

With this code example in Objective-C you can consult your account balance using the LabsMobile API SMS.

Through a call to this endpoint, you can get information about the amount of credits available in your LabsMobile account. The connection is established through a HTTP/GET request with authentication in the HTTP connection header.

#import <Foundation/Foundation.h>
int main(int argc, const char * argv[]) {
   @autoreleasepool {
       dispatch_semaphore_t sema = dispatch_semaphore_create(0);
      

       NSString *username = @"myUsername";
       NSString *token = @"myToken";
      
       NSString *authString = [NSString stringWithFormat:@"%@:%@", username, token];
       NSData *authData = [authString dataUsingEncoding:NSUTF8StringEncoding];
       NSString *base64AuthString = [authData base64EncodedStringWithOptions:0];
      
       NSDictionary *headers = @{
           @"Content-Type": @"application/json",
           @"Authorization": [NSString stringWithFormat:@"Basic %@", base64AuthString]
       };
      
       NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.labsmobile.com/json/balance"]
                                                                 cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                             timeoutInterval:10.0];
       [request setAllHTTPHeaderFields:headers];
       NSData *postData = [[NSData alloc] initWithData:[@"" dataUsingEncoding:NSUTF8StringEncoding]];
       [request setHTTPBody:postData];
       [request setHTTPMethod:@"GET"];
      
       NSURLSession *session = [NSURLSession sharedSession];
       NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                   completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
           if (error) {
               NSLog(@"%@", error);
               dispatch_semaphore_signal(sema);
           } else {
               NSError *parseError = nil;
               NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
               NSLog(@"%@",responseDictionary);
               dispatch_semaphore_signal(sema);
           }
       }];
       [dataTask resume];
       dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
   }
}

{"code":0,"credits":"10"}

See the complete documentation at:

Documentation Balance inquiry

Receive status of sent messages

This example script receives a call from the LabsMobile platform when a sent SMS message changes status. To implement this solution, it is essential to configure the appropriate parameters, the confirmation URL in the ackurl parameter in the request or the default URL in the API Settings of your account.

Therefore, it is necessary to publish a script like this in your system so that our platform calls the URL when a status change occurs in any of the sent messages.

The example code obtains the URL parameters using the global $_GET variable and then assigns these parameters to local variables.

#import <Foundation/Foundation.h>#import <GCDWebServer/GCDWebServer.h>
@interface MyWebServer : NSObject

@property (nonatomic, strong) GCDWebServer *webServer;

- (void)startServer;

@end

@implementation MyWebServer

- (instancetype)init {
   self = [super init];
   if (self) {
       _webServer = [[GCDWebServer alloc] init];
   }
   return self;
}

- (void)startServer {
   [self.webServer addDefaultHandlerForMethod:@"GET" requestClass:[GCDWebServerRequest class] processBlock:^GCDWebServerResponse *(GCDWebServerRequest *request) {
       NSDictionary *queryParams = request.query;
       NSString *acklevel = queryParams[@"acklevel"];
       NSString *credits = queryParams[@"credits"];
       NSString *msisdn = queryParams[@"msisdn"];
       NSString *status = queryParams[@"status"];
       NSString *subid = queryParams[@"subid"];
       NSString *timestamp = queryParams[@"timestamp"];

       NSLog(@"Variable acklevel : %@", acklevel);
       NSLog(@"Variable credits : %@", credits);
       NSLog(@"Variable msisdn : %@", msisdn);
       NSLog(@"Variable status : %@", status);
       NSLog(@"Variable subid : %@", subid);
       NSLog(@"Variable timestamp : %@", timestamp);

       return [GCDWebServerResponse responseWithStatusCode:200];
   }];

   [self.webServer startWithPort:3000 bonjourName:nil];
   NSLog(@"Server started at port 3000");
}

@end

int main(int argc, const char * argv[]) {
   @autoreleasepool {
       MyWebServer *server = [[MyWebServer alloc] init];
       [server startServer];
       [[NSRunLoop currentRunLoop] run];
   }
   return 0;
}

See the complete documentation at:

Documentation Receipt of sent SMS statuses

Receiving SMS messages

Once you have contracted a virtual number, you will be able to receive messages via API on a specific URL via a HTTP/GET call to a script in your system. Each message received will invoke the URL, transmitting all its data in variables in JSON format.

To activate this functionality you must inform the URL for receiving messages in the Settings of your account.

It is necessary to configure an endpoint in your system so that the LabsMobile platform calls this script when an SMS is received on any of the contracted virtual numbers.

The example code obtains the URL parameters using the global variable $_GET and then assigns these parameters to local variables.

#import <Foundation/Foundation.h>#import <GCDWebServer/GCDWebServer.h>
@interface MyWebServer : NSObject

@property (nonatomic, strong) GCDWebServer *webServer;

- (void)startServer;

@end

@implementation MyWebServer

- (instancetype)init {
   self = [super init];
   if (self) {
       _webServer = [[GCDWebServer alloc] init];
   }
   return self;
}

- (void)startServer {
   [self.webServer addDefaultHandlerForMethod:@"GET" requestClass:[GCDWebServerRequest class] processBlock:^GCDWebServerResponse *(GCDWebServerRequest *request) {
       NSDictionary *queryParams = request.query;
       NSString *inbound_number = queryParams[@"inbound_number"];
       NSString *service_number = queryParams[@"service_number"];
       NSString *msisdn = queryParams[@"msisdn"];
       NSString *message = queryParams[@"message"];
       NSString *timestamp = queryParams[@"timestamp"];

       NSLog(@"Variable inbound_number : %@", inbound_number);
       NSLog(@"Variable service_number : %@", service_number);
       NSLog(@"Variable msisdn : %@", msisdn);
       NSLog(@"Variable message : %@", message);
       NSLog(@"Variable timestamp : %@", timestamp);

       return [GCDWebServerResponse responseWithStatusCode:200];
   }];

   [self.webServer startWithPort:3000 bonjourName:nil];
   NSLog(@"Server started at port 3000");
}

@end

int main(int argc, const char * argv[]) {
   @autoreleasepool {
       MyWebServer *server = [[MyWebServer alloc] init];
       [server startServer];
       [[NSRunLoop currentRunLoop] run];
   }
   return 0;
}

See the complete documentation at:

Documentation Receipt of SMS messages

Support resources

We recommend that you consult and take into account the following support resources in your integration: