NowSMS PHP Example: Send MMS Message

Continuing our series of PHP examples, today we'll revisit sendmms.php, which we originally published on our discussion board 5 years ago at http://www.nowsms.com/discus/messages/1/1113.html.

The sendmms.php script is considerably more complex than the sendsms.php script. The reason for this increased complexity is because an MMS message is more complex than an SMS message.

However, I have to admit that our 5 year old example can be a little difficult to follow. Over the years, I've answered quite a few questions about the script, as the way that you specify the files to include in the MMS message is a little confusing.

So in this posting, we'll update sendmms.php, and make it a little easier to follow.

The updated sendmms.php can be downloaded at http://www.nowsms.com/download/sendmms-php.txt.

The first part of sendmms.php consists of PHP functions that you will call in your PHP script ... namely MmsInit, MmsAddField, MmsAddFile and MmsSend. Include these functions in your script without editing them.

After these functions are defined, sendmms.php contains a simple example showing how to use these functions to send an MMS message through a NowSMS server.

1.) First, you need to initialise the parameters to point to your NowSMS server:

/* Set parameters for connecting to the NowSMS server */
$nowsmsHostName = "127.0.0.1"; /* IP Address or host name of NowSMS Server */
$nowsmsHostPort = "8800"; /* NowSMS Port number for the web interface */
$nowsmsUsername = "test"; /* "SMS Users" account name */
$nowsmsPassword = "test"; /* "SMS Users" account password */

2.) Second, you need to call MmsInit to initialise the MMS message structure.

$mmsMessage = MmsInit();

3.) Third, you need to add the necessary MMS header fields and attributes desired for your MMS message, calling the MmsAddField fuction.

$mmsMessage = MmsAddField ($mmsMessage, "PhoneNumber", "+447777777777");
$mmsMessage = MmsAddField ($mmsMessage, "MMSFrom", "sender@domain.com");
$mmsMessage = MmsAddField ($mmsMessage, "MMSSubject", "Subject of Message");

The "PhoneNumber" field specifies the recipient(s) for the MMS message. This can be a comma delimited list of phone numbers, or it can be the name of a NowSMS distribution list.

The "MMSFrom" field specfies the sender of the MMS message. Normally, this would be a phone number, short code or e-mail address. (And your MMS service provider may either require a specific value here, or they may overwrite the value you supply with the address associated with your service.)

The "MMSSubject" field specifies the subject of the MMS message.

Those are the most common MMS header fields. Optionally, you might also want to include an "MMSText" field to specify some text to be included in the MMS message. Text can also be included in an MMS message as a text file reference.

4.) Fourth, you specify the files to include in the MMS message using the MmsAddFile function. These files might be images, video, text, or other file types supported by the receiving device.

$mmsMessage = MmsAddFile ($mmsMessage, "f:\\temp\\filename.gif", "image/gif");

An MMS message can contain one or more of these included files. If you do not include a SMIL file component, NowSMS will build one automatically, so for full control of the MMS message presentation, you will want to include your own SMIL file, where you reference your file components by their short filename (without the full path, e.g., filename.gif ... NOT f:\temp\filename.gif).

The files referenced in the PHP script must be local files, residing on the same server as the PHP script. Remember to escape backslashes in the path so as not to confuse the PHP interpreter(c:\temp\file becomes c:\\temp\\file).

The last parameter of MmsAddFile is the MIME content type, e.g., "image/gif", "image/jpeg", "image/png", "text/plain" or "application/smil" ... however, note that current versions of NowSMS ignore the MIME content type when messages are submitted via the interface used by this PHP script. Instead, NowSMS uses the file extension to determine the content type (e.g., ".gif", ".jpg", ".png", ".txt", ".smil").

5.) Fifth and finally, you call MmsSend to submit the MMS message.

MmsSend ($nowsmsHostName, $nowsmsHostPort, $nowsmsUsername, $nowsmsPassword, $mmsMessage);

Those are the basics.

For the curious, the MmsAddField function can be used to specify any NowSMS URL parameter that is valid for sending an MMS message.

For example ... here is an incomplete list of additional parameter fields that can be specfied using the MmsAddField function.

"MMSFile" - As I've noted above, this script attaches local files to the MMS message. However, what if you want to include files that reside on a separate web server instead? In that case, do not use the MmsAddFile function. Instead, use $mmsMessage = MmsAddField ($mmsMessage, "MMSFile", "http://www.nowsms.com/media/logo.png" ); and specify the file components as URL references via the "MMSFile" parameter field.

"MMSDeliveryReport" - "Delivery Report" specifies whether or not a delivery report is requested for the message. Set to "Yes" to request a delivery report. Note that any delivery report would be directed back to the phone number or e-mail address specified in the "MMSFrom" address.

"MMSReadReport" - "Read Report" specifies whether or not a read receipt is requested for the message. Note that the receiving client may choose not to send a read receipt. Any read receipt report would be directed back to the phone number or e-mail address specified in the "MMSFrom" address.

"MMSPriority" - "Priority" is a user defined priority to be associated with the message. Generally, any priority definition associated with the message is ignored by the underlying transport, but the receiving client may decide to display messages differently based upon this priority setting.

"MMSMessageClass" - "Message Class" is an attribute defined in the MMS specifications. "Personal" is the message type that is used for standard user-to-user communications. Other defined message classes that are supported by this parameter include: "Informational" and "Advertisement".

"MMSWAPPush" - Set to "Yes" to indicate that the message being sent should be sent as an "Multimedia WAP Push" message instead of as an MMS message.

It is also possible to specify forward locking and DRM constraints to be applied against the content of the MMS message. Forward locking and DRM constraints apply to non-text parts of the MMS message (i.e., in a forward locked message, text could still be forwarded, but images or video could not). Please note that not all devices support forward locking and DRM constraints, therefore use these parameter settings only after testing thoroughly with mobile phones used by your message recipients.

"MMSForwardLock" - Forward locking is the most basic level of DRM (Digital Rights Management). When "Forward Lock" is set to "Yes", this indicates that the receiving device should not allow any non-text objects in the message to be forwarded off of the device. The device may allow the user to extract pictures, videos or sounds from the message and save them on the phone. However, any such objects remain forward locked, such that they cannot be forwarded to another user or transferred to another device. (IMPORTANT NOTE: NOT ALL DEVICES SUPPORT FORWARD LOCK, WHEN NOT SUPPORTED THE CONTENT WILL APPEAR AS GARBAGE OR MAY BE REJECTED BY THE OPERATOR MMSC.)

"DRMRestrict" - Beyond forward locking, More advanced DRM (Digital Rights Management) restrictions can be applied to limit the number of times that the user can access an object, or start and end dates can be specified to limit how long the user can access an object.
These advanced DRM restrictions can be applied by setting "DRMRestrict" to "Yes". When this setting is enabled, forward lock is also implied, and the value of the "MMSForwardLock" setting is ignored. (IMPORTANT NOTE: NOT ALL DEVICES SUPPORT DRM RESTRICTIONS, WHEN NOT SUPPORTED THE CONTENT WILL APPEAR AS GARBAGE OR MAY BE REJECTED BY THE OPERATOR MMSC.)

"DRMRestrictTextXML" - "Yes" specifies that the rights object should be encoded in text XML format. "No" specfies that the rights object should be encoded in binary XML format. The default is "No".

When DRM Restrictions are specfied, it is generally necessary to specify one or more DRM Permissions and one or more DRM Constraints regarding the MMS message content.

DRM Permissions specify what types of access are allowed against the objects in a message that is protected with DRM.

For example, an audio or video object requires "Play" permission before the user can access it. An image requires "Display" permission before the user can access it, and it requires "Print" permission if the user is to be allowed to print the image to a printer , perhaps over Bluetooth. An application requires "Execute" permission before the user can make use of the application. In all cases, the forward locking is assumed, so that the user is not allowed to forward or transfer the object from the device.

If you are sending multiple types of objects in the MMS message, specify all permissions that are required for the different types of objects that are being sent.

"DRMPermissionPlay" - Set to "Yes" to enable DRM "Play" Permission.

"DRMPermissionDisplay" - Set to "Yes" to enable DRM "Display" Permission.

"DRMPermissionExecute" - Set to "Yes" to enable DRM "Execute" Permission.

"DRMPermissionPrint" - Set to "Yes" to enable DRM "Print" Permission.

DRM Constraints specify constraints with regard to how long a DRM protected object object should remain accessible to the user.

"DRMConstraintCount" - "# of Accesses (count)" specifies the the user can only access the DRM protected object this number of times before access is no longer allowed.

"DRMConstraintStart" - "Start Date (yyyy-mm-dd)" specifies that the user will not be allowed to access the DRM protected object until on or after the specified date. (Note that you must specify the date in yyyy-mm-dd format, e.g., 2008-12-24.)

"DRMConstraintEnd" - "End Date (yyyy-mm-dd)" specifies that the user will not be allowed to access the DRM protected object after the specified date. (Note that you must specify the date in yyyy-mm-dd format, e.g., 2008-02-24.)

"DRMConstraintInterval" - "# of Days (interval)" specifies that the user will be allowed to access the DRM protected object for this number of days after initial receipt of the object. The user can either enter a number of days here, or they can enter any valid value defined for the "" element in the OMA DRM Rights Expression Language specification. For example, P2Y10M15DT10H30M20S represents a duration of 2 years, 10 months, 15 days, 10 hours, 30 minutes and 20 seconds.

NowSMS PHP Example: Send SMS Text Message

Over the coming weeks, I'm planning to collect various PHP, ASP and other script examples to provide some examples of how to interface with NowSMS from those environments.

The following links should provide all of the relevant postings, assuming that I follow-up with this task as planned.

PHP Examples -- http://blog.nowsms.com/search/label/PHP

ASP Examples -- http://blog.nowsms.com/search/label/ASP

Command Line Script Examples -- http://blog.nowsms.com/search/label/command%20line%20interface

We'll start with the simplest of examples, sending an SMS text message from a PHP script.
It was almost five years ago that we posted an example PHP script for this task on our discussion board at http://www.nowsms.com/discus/messages/1/867.html.

Below I've included basically the same five year old script, but I've added some minor comments for further clarification.

The SendSMS function is the important part of the example. This is the function that needs to be included in your PHP script. You call this function, specifying the host name or IP address and port number of the NowSMS server, along with a username and password for an "SMS Users" account on the NowSMS server, plus the recipient phone number and text of the SMS message.

The SendSMS function uses these parameters to build a URL for connecting to the NowSMS server. This function could be easily modified to support sending other types of messages by modifying the URL that the function creates. For additional information on NowSMS URL parameters, see http://www.nowsms.com/documentation/ProductDocumentation/sending_messages/url_parameters_for_sending_messages.htm.

Following the SendSMS function, we show two examples of how this function might be called from within a PHP script.

The first example shows hard coded parameters being passed to the SendSMS function.

The second example shows how a web form could post to the PHP script. The PHP script parses the variables received from the web form, and passes those variables to the SendSMS function to trigger NowSMS to send a message.

<? function SendSMS ($host, $port, $username, $password, $phoneNoRecip, $msgText) { /* Parameters: $host - IP address or host name of the NowSMS server $port - "Port number for the web interface" of the NowSMS Server $username - "SMS Users" account on the NowSMS server $password - Password defined for the "SMS Users" account on the NowSMS Server $phoneNoRecip - One or more phone numbers (comma delimited) to receive the text message $msgText - Text of the message */ $fp = fsockopen($host, $port, $errno, $errstr); if (!$fp) { echo "errno: $errno \n"; echo "errstr: $errstr\n"; return $result; } fwrite($fp, "GET /?Phone=" . rawurlencode($phoneNoRecip) . "&Text=" . rawurlencode($msgText) . " HTTP/1.0\n"); if ($username != "") { $auth = $username . ":" . $password; $auth = base64_encode($auth); fwrite($fp, "Authorization: Basic " . $auth . "\n"); } fwrite($fp, "\n"); $res = ""; while(!feof($fp)) { $res .= fread($fp,1); } fclose($fp); return $res; } /* This code provides an example of how you would call the SendSMS function from within a PHP script to send a message. The response from the NowSMS server is echoed back from the script. $x = SendSMS("127.0.0.1", 8800, "username", "password", "+44999999999", "Test Message"); echo $x; */ /* This code provides an example of sending a message via NowSMS as the result of a web form posting. First, here's a very simple HTML web form that provides an example of what you need in your web form. <HTML> <HEAD><TITLE>Send SMS</TITLE></HEAD> <BODY> <form method="post" action="sendsmsscript.php"> <table border="1"> <tr> <td>Mobile Number:</td> <td><input type="text" name="phone" size="40"></td> </tr> <tr> <td valign="top">Text Message:</td> <td><textarea name="text" cols="80" rows="10"></textarea> </tr> <tr> <td colspan="2" align="center"> <input type="submit" value="Send"> </td> </tr> </table> </form> </BODY> </HTML> Second, here's the PHP script that would parse the parameters from the form posting, and then call the SendSMS function to submit the message. if (isset($_REQUEST['phone'])) { if (isset($_REQUEST['text'])) { $x = SendSMS("127.0.0.1", 8800, "username", "password", $_REQUEST['phone'], $_REQUEST['text']); echo $x; } else { echo "ERROR : Message not sent -- Text parameter is missing!\r\n"; } } else { echo "ERROR : Message not sent -- Phone parameter is missing!\r\n"; } */ ?>

2-way SMS: Multiple operators with the same shortcode

This configuration issue comes up quite a bit.

Let's say that you are connecting directly to multiple mobile operators, and your service is using the same short code on each operator. When customers send a message in to your short code, you want to make sure that the reply is sent back via the same mobile operator as which the message was received.

Additionally, if that message from the customer is a trigger to begin receiving updates from your service, you want to ensure that any additional messages that you send to the customer get routed back through the same mobile operator SMSC connection.

I'm going to address the simple 2-way SMS reply first.

If you are using the same short code on both SMSC connections, then replies will not automatically be directed out via the same SMSC connection from which the original message was received. (If you are using different short codes, then make sure that the appropriate short code is configured as the "Default Sender Address" for the SMSC connection, and this situation will fix itself.)

How to resolve this situation when using the same short code on multiple SMSC connections?

There's a short easy answer, and a long more difficult answer.

Short (Easy) Answer:

If you're running NowSMS v2008.03.22 or later, edit SMSGW.INI, and under the [SMSGW] header, add 2WayReplySameServer=Yes.

(Note: At the time this article was written, v2008.02.22 is the official download version. An updated release that includes this functionality, can be downloaded at http://www.nowsms.com/download/nowsmsupdate.zip.)

Restart the NowSMS server.

We could not make this setting a default, because there are actually quite a few NowSMS installations where for various operational reasons, 2-way SMS replies need to be sent out via a different connection from which they were received.

Note that this setting only applies to simple 2-way commands, where the command script returns a text response back directly. This setting does not apply when the "redirect technique" is used. That configuration is described in more detail in the Long More Difficult Answer.

Long (More Difficult) Answer:

For more advanced logic in 2-way command scripts, it is sometimes necessary to use the "redirect technique" that is described in the following document: http://www.nowsms.com/support/bulletins/tb-nowsms-003.htm

Alternatively, instead of using the "redirect technique", your 2-way command script might initiate a new HTTP request to the NowSMS server to tell NowSMS to send one or more messages. For simple examples of this, see http://www.nowsms.com/discus/messages/1/3991.html, http://www.nowsms.com/discus/messages/1/867.html or http://www.nowsms.com/support/bulletins/tb-nowsms-008.htm.

With these types of 2-way command scripts, NowSMS passes the received message to the command script. But then the command script generates a new URL request back to NowSMS to send a message. In this context, NowSMS does not see the new URL request as a reply, so it cannot apply the desired routing logic.

This section describes how to achieve the desired routing logic when you are generating your own URL request for NowSMS.

The "Command to Execute" defined for your 2-way command script must include an @@SMSCROUTE@@ variable. When NowSMS passes the received message to your 2-way command script, NowSMS will replace @@SMSCROUTE@@ with the SMSC name (or assigned route name).

When your 2-way command script receives the message, it must parse the @@SMSCROUTE@@ value. This is how your 2-way command script knows the mobile operator SMSC connection from which this message was received.

If your 2-way command wants to reply back to the message, it needs to build a URL request for NowSMS. This URL request must include an "&SMSCRoute=xxxx" parameter which contains the original @@SMSCROUTE@@ parameter that was passed to the 2-way command. This tells NowSMS that the resulting message should only be sent out via that specified route.

By default, the @@SMSCROUTE@@ value is going to be the host name as defined in the NowSMS "SMSC" list (e.g., "SMPP - 10.1.1.1:9000" or "Modem - Bluetooth Modem"). It is possible to manually edit the NowSMS SMSGW.INI file to assign a more meaningful route name. Under the appropriate section header for each SMSC connection (e.g.,"SMPP - 10.1.1.1:9000" or "Modem - Bluetooth Modem), it is possible to include a RouteName=xxxxxxxx parameter, where xxxxxxxx will instead be used as the @@SMSCROUTE@@ value.

I know what you're saying ... that seems complicated. It's really not all that complicated ... it just seems so because so far I've been too lazy to provide you with an example. I don't know about you, but I usually do better with examples myself.

Let's say you've got 2 SMPP connections to different mobile operators.

You've manually edited SMSGW.INI, and under one of the [SMPP - server:port] sections, you've added RouteName=Operator1, and under the other [SMPP - server:port] section, you've added RouteName=Operator2.

Let's say that you're using PHP for your scripting language, and you've created a PHP script named 2way.php which is installed on one of your web servers.

Configure the following 2-way command:

SMS Command Prefix = * (applies to all received messages, unless a better match exists)

Receive Phone Number(s) = (leave blank or put in your short code here to apply this script to messages only received by that short code)

Command to Execute = http://server/2way.php?sender=@@SENDER@@&text=@@FULLSMS@@&shortcode=@@RECIP@@&SMSCRoute=@@SMSROUTE@@

"Command Returns Response Text" should NOT be checked for this type of command script.

If the phone number 14435551212 sends a text message "TEST" to your short code 11111, and it is received via the SMSC connection defined with RouteName=Operator1, then the following URL would be triggered by NowSMS when the message is received:

http://server/2way.php?sender=14435551212&text=TEST&shortcode=11111&SMSCRoute=Operator1



Because of the indenting here, the script is a little difficult to follow. But basically, this script is just parsing the "sender" (@@SENDER@@ value), "text" (@@FULLSMS@@ value) and "smscroute" (@@SMSROUTE@@ value) parameters that were passed to the script.

The script then builds a new URL that it passes back to NowSMS to tell NowSMS to send a new message back to the sender via the same route as from which the message was received.

In this example, the script would return the following URL in a redirect response:

http://127.0.0.1:8800/?phonenumber=14435551212&text=I+received+your+message%3A+TEST&smscroute=Operator1

This URL redirect tells NowSMS to send a message back to the originator via the same operator SMSC as the originating message.

A few additional notes on this example....

This example assumes that the web interface for NowSMS is listening on its default port of 8800. If it is using a different port, the port number needs to be changed in the script.

127.0.0.1 assumes that this script will only be used if triggered by a NowSMS 2-way command. If you want to test the script by connecting to it from a web browser, change 127.0.0.1 to the IP address of the NowSMS server.

This example also assumes that "Require Authentication for web interface" is not enabled on the "Web" page of the NowSMS configuration. If this setting is enabled, then modify the "header" command in the script, so that after $_REQUEST['smscroute'] and before ); the following is added: . "&user=username&password=password"

The username and password values should match an account defined on the "SMS Users" page of the NowSMS configuration.

If you will be sending SMS messages to the subscriber outside of the context of a 2-way command, then you need to save the @@SMSCROUTE@@ value that you obtained when the subscriber originally sent into your system. You would save this value in your own database, maintained by your own applications, it is not saved by NowSMS. When sending any messages to that subscriber, generate a URL request for NowSMS that includes this route information in the "&SMSCRoute=" parameter.