Since we introduced client access to our social media and marketing platform we've aggregated 30 million news articles, truncated over 50 million links, sent over 5 million individual posts to social media, and we've helped hundreds of business achieve their desired growth outcomes. However, despite the overwhelming success of our platform tools, we'll shortly be introducing our new multi-user, self-hosted, and fully branded product that we'll make available to all clients.

Update: The module described in this article is now part of the BM Marketing & Social Studio - details here. Those clients that have access to the deprecated features have continued support on that system until they've migrated to the new Platform. The middle-man API is one that will continue to function.

The purpose of this article, discussed in four parts, is to introduce some of the functionality associated with our new text messaging module.

1. New Self-Hosted Social & Marketing Platform.
2. API usage, and PHP code for standalone applications.
3. Text Messaging SMS features integrated into our platform.
4. Updating API Keys.

Keep in mind that the SMS Integration is just one of about 50 primary modules we make available via our platform. The (new) system is still largely in development but we expect full access to be made available to all clients by next month.

1. The New Platform (Coming Soon)

Our platform has long resided at clients.beliefmedia.com. One issue that's always concerned us (above all else) was that of branding. We tend to always build our own tools and website plugins, and we provide an array of various online tools to mitigate the need to source 'paid' products. Everything we provide our clients gives the outward impression of 'ownership' - even if hosted by us. However, the platform that is the centre of our social operations was (and remains) hosted by us. It's this issue that was at the heart of my decision to sanction the development of a suite of tools that will effectively provide all the features of the current platform in a self-hosted and self-branded environment. This means that your decision to work with us means having a platform as sophisticated as the most costly premium social media services all hosted in a subdomain on your own website. This self-hosted suite includes the countless tools you won't find anywhere else.

The nature of the new service is API-centric, meaning that all requests performed on your website are sent to us for processing. This means that most of your social data is available from within other applications... and it paves the way for us to create mobile applications using the same system.

The self-hosted services works great for franchise operations that have multiple shopfronts, or businesses with multiple employees. The new system allows you to create your own users and control their access to only those features or social accounts you choose to make available (although they can add their own, or you may allocate one of your accounts to them with an optional expiry). Additionally, sub-users will only see content they've created or scheduled themselves. The remote platform administrator will have access to all events created via their hosted system.

While all features of the 'old' platform (and some newer tools) will all be ported over to the new system over coming months, all those APIs that have undergone testing are available via your own standalone applications, or from within WordPress via your own functions. The first API we'll introduce is the API to send Telstra SMS messages.

2. Telstra Text Messaging API

Text messaging has long been a part of our platform, and messaging has formed an integral component of our various marketing campaigns for a number of years. However, we've never been happy with the single messaging service we offered. The new system will integrate with a growing number of third-party SMS gateways - including our own (giving you the choice to use any service).

One of the first providers we integrated is Australia's Telstra . While you can happily integrate the Telstra API with your own system yourself, we essentially provide a wrapper that integrates the text messaging features into our own platform. This means that text messaging can easily be used with existing campaigns that utilise email, social, and other lead-related methods.

Quite frankly, if SMS messaging isn't already part of your marketing strategy - with its open rate of upwards of 95% - you need to rethink your business strategy.

Telstra API Features

The features of each API service varies. Those provided by way of the Telstra API (as integrated into our system) are as follows:

• Send SMS and MMS text messages of up to 1900 UTF-8 characters.
• If on a paid Telstra plan (Telstra charge you for messages - not us), you may use an alphanumeric sender ID of up to 11 characters. If not present, the service will use the provisional mobile number associated with the application (phone number in E.164 format).
• Email sent upon email acceptance (notifications are disabled via the control panel).
• Replies forwarded via email (and also sent to a number if you have a paid plan with an associated and valid number).
• Scheduling the message from within the SMS post request. This delays delivery for a period of time (we also provide scheduling on our end).
• Sending the same message to multiple recipients.
• Any message with a STOP reply will stop the recipient from receiving any further communication via our system, update your leads database, and optionally notify you via email of the unsubscription.

On our end, the messages are recorded with the user associated with your platform, and we archive all messages and replies for auditing. We've created a fairly crude CMS for the purpose of creating contacts (supplemented by email systems) and from this data you may create lists of SMS recipients. For administration purposes, statistics are returned for the number of messages sent via each of your users.

PHP Function Example

The following is an example of how you might send a text message using PHP (the WordPress version is integrated into the self-hosted plugin). You'll need a BeliefMedia client key and client secret (the key is used for most basic requests... with the secret key used when communicating with your own data). An individual API is also required if using the API from within our self-hosted service (the key is automatically generated when each user is added to your platform by your company administrator, and it's seamlessly integrated with each request). You'll also need to register your own Telstra application and obtain a client_id and client_secret. If you're using our Platform WordPress plugin, all keys are entered via a control panel.

It's necessary to provide an array that includes the to address, the from address, the message body, your childuserid, and the SMS action (in this case, an action associated with a service provider). In the following array, we've nominated the action (or service provider) as 2 (Telstra), and we've used a childuserid as 1 (this will be a WP User ID if using our plugin). If you have a paid messaging subscription with Telstra you should also include the from field (the alphanumeric sender ID of up to 11 characters can be different for each user).

$query_array = array('to' => '+61400XXXXXX', 'body' => 'SMS Text Message.', 'childuserid' => '1', 'action' => '2');

Keep in mind that it's only necessary to build the array if you're using the API outside of our plugins.

Basic encryption is applied to the query data supplied to our system. The common function below is not a bullet proof means of data protection but it's more than suitable for our application. The secret key (which is not transported) is used to encrypt and restore the JSON string.

• The phone number should be provided in an international format (starting with a + including country code).
• If using our plugin, the keys will obviously be applied automatically.
• The function returns a JSON response indicating a successful or failed request.
• The same text message is sent to multiple numbers by using a comma delimited string of numbers in the to field.
• Telstra returns a POST response to our system and those details are recorded in our system (available as detailed below). If you'd like the Telstra response to be sent to your website, include a notifyURL in the $query_array.
• We provide a scheduling feature from within our system. However, you may provide a schedule from within your $query_array. Use scheduledDelivery as the array key and the minutes as the value.

3. Sending Text Messages Via The BeliefMedia Platform

Sending text messages via your self-hosted and fully branded marketing platform is the preferred means of using the API. Following is just a few features.

Sending Individual Messages

Sending to a single recipient is achieved by either selecting the recipient from a select menu, or searching for them in your contacts database and selecting "Send SMS".

Via the contact list, selecting "Send SMS" will redirect to you to the SMS page or launch a modal popup (depending upon preferences).

Scrolling down on the same page presents the form to send text messages to lists.

Sending to SMS Lists

Sending to lists (the creation of which is discussed below) is accomplished with ease. Simple provide a campaign name (for your own reference), optionally schedule a time to start sending, select the desired list, create the 160 character message, and click 'Schedule New Campaign".

Available placeholders are %%firstname%% and %%lastname%%... although we expect to add more when the need presents itself.

Creating SMS Lists

Lists are automatically created based on data provided when creating a contact (geographic region, employment type, occupation etc), or created by you (all lists are available from the schedule form pictured above). To create a list, click the "SMS Lists" menu item and you will be presented with a form where you can add recipients to a list, or edit an existing list.

When sending a link to a list of recipients, we suggest creating a shor.tt URL to determine total page visits. We'll automatically create a new shor.tt URL for each user (from the provided URL) so you're able to determine if individual recipients followed a link, and it enables us to build accurate statistical data.

We also permit web-based or form-click subscription opt-ins for any chosen SMS campaign (handy for events etc).

Message Logs

We provide two logs - one that provides a log of all platform actions, and the second recording send and received (confirmation) receipts from Telstra.

A summary page of all pending, sent, and draft campaign is also provided via the "SMS Campaigns" menu link.

4. API Keys

We require API keys for the BeliefMedia platform to be entered via the primary user administration area (not visible to child users). For text messaging purposes we also require a Telstra API Key and Secret pair as provided via their platform. The system will automatically generate a number of other keys and return them back to you for reference purposes (although the shor.tt and fat.ly keys are issued without any expiry).

Primary Keys. Required: BM API Key & Secret.

If we've set up the Telstra application for you, you'll simply (and optionally) retrieve the associated keys by selecting "Retrieve Keys" (pictured below). If you don't have a paid plan (i.e. you're on a trial plan), or you haven't defined an alphanumeric caller ID, the provisional number allocated to you and its expiry date are also returned. If we don't have your Telstra keys recorded on our system you'll have to submit that data before SMS text messaging features are available.

Telstra SMS Keys.

Each child user in your system is allocated an API Key that is used to identify them (along with platform details) with each request. The same API Key may be used by them to access any API data made available on our website . While we issue all API keys without an expiry date, you can control, suspend, and set your own users' expiry date yourself from the administration control panel. As the primary user, your basic API key is issued perpetually and is available to use in compliance with platform policies. It's only the BeliefMedia API Secret that may have an expiry.

Each user may find their personal API key from within their Control Panel (as pictured below).

BeliefMedia API Key. Issued without an expiry.

Note: We'll revisit the nature of API Keys when the system makes its way into the wild.

Considerations

• If you're serious about SMS marketing, consider using a dedicated Smart Number for all your internal SMS communications.
• If we do not currently support your exitsing SMS provider from within our system, get in touch and we'll make it happen. We generally require a few days to build the integration.
• To send messages you'll require the Requests library (hosted on Github). We're using this library for data transport because it's integrated with WordPress by default.
• There are a number of laws that apply to text messaging marketing. The Governing legislation in Australia is the Spam Act (2003) , and the AMCA provides a reasonable summary of applicable responsibilities . We require that all messages sent via our system complies with applicable legislation. Your upline source provider (if not us) will invariably require the same.