flowroute-messaging-python is a PHP SDK that provides methods to create and send an outbound SMS from a Flowroute phone number and to retrieve a Message Detail Record (MDR) using he MessageController. These methods use v2 (version 2) of the Flowroute API.
Note: This SDK does not cover searching for a set of MDRs based on a date range. For searching on a date range, see Look up a Set of Messages on the Flowroute Developer Portal.
The full documentation for the v2 Flowroute API is available here.
Before you begin
The following are required before you can deploy the SDK.
Have your API credentials
You will need your Flowroute API credentials (Access Key and Secret Key). These can be found on the Preferences > API Control page of the Flowroute portal. If you do not have API credentials, contact email@example.com.
Know your Flowroute phone number
To create and send a message, you will need your Flowroute phone number, which should be enabled for SMS. If you do not know your phone number, or if you need to verify whether or not it is enabled for SMS, you can find it on the DIDs page of the Flowroute portal.
Get a code text editor
Steps in this SDK describe creating one or more script files that allow you to execute the methods. Script files can be created either using a terminal window shell or through using a code text editor. For example, Sublime Text.
Composer is used to manage the dependencies for the PHP SDK. The Composer installation file, composer.phar, can be downloaded from Composer's web site here. Download, but do not install it; only after first installing the libraries will you install Composer.
Install the libraries
Note: You must be connected to the Internet in order to install the required libraries.
Open a terminal session.
If needed, create a parent directory folder where you want to install the SDK.
Go to the newly created directory, and run the following:
git clone https://github.com/flowroute/flowroute-messaging-php.git
git clonecommand clones the flowroute-messaging-php repository as a sub directory within the parent folder.
Change directories to the newly created flowroute-messaging-php directory.
Move the downloaded composer.phar file to the flowroute-messaging-php directory.
Note: composer.phar must be in the flowroute-messaging-php directory in order to install correctly. Composer requires a composer.json file, which is included in the imported SDK to help manage dependencies.
From a terminal window, run the following:
php composer.phar install
Composer sets up the required file structure.
With the directory structure set up and Composer installed, you can now invoke the methods to perform functions within the SDK. There are two ways of doing this.
Two demo files, demo_send.php and demo_recv.php, are included with the installed libraries. These files contain the information necessary to invoke each of the methods. You invoke the methods in either of these files by adding your API credentials to the files, then running each file from a terminal window command line:
For information on the parameters within the file, see MessagesController.
The following describes importing the SDK and setting up your API credentials. Importing the SDK allows you to instantiate the MessageController, which contains the methods used to create and send messages, and to look up an MDR. Do this by first creating a file with a code text editor, or through the terminal shell.
Using a code text editor create a new file and add the following lines to the top of the file to instantiate the Controller and import the Models:
<?php require_once('vendor/autoload.php'); #Instantiate the Controllers use FlowrouteMessagingLib\Controllers\MessagesController; use FlowrouteMessagingLib\Models\Message;
Next add the following lines to authorize your API credentials to work with the Controller:
#Pass your API credentials $controller_name = new MessagesController('Access Key','Secret Key');
Secret Keyvariables with your Flowroute API credentials.
Optionally, add a print response line to the end of the file. By adding this line, when a method is invoked, the print response displays the response on screen:
#Print the Response print_r($response);
Important: Throughout this document,
responseis used in method examples.
responseis a variable name that can be changed to a name of your own choosing. It can support an unlimited number of characters. If you choose to rename
response, make sure that any method that references that variable name is also changed to use the new name. In the following example,
responseis changed to
#Create and Send a Message
$message_name = new Message('To', 'From', 'Message content');
$blob = $controller->createMessage($message_name);
Save the file with a PHP extension in your flowroute-messaging-php directory. For this example, the file is named createmsg.php.
Add the Controller methods. See MessagesController below.
Note: In the example above, the
$response = $controller->getMessageLookup('recordID')are commented out. These lines are not needed if you do not need to retrieve an MDR ID for the
getMessageLookupmethod. See getMessageLookup if you need this information.
Example PHP file
The following shows an example PHP file with all methods added. Before invoking a method, comment out any other method with
# as needed. For example, you might want to comment out the createMessage method lines when invoking the getMessageLookup method, and vice versa.
<?php require_once('vendor/autoload.php'); #Instantiate the Controllers use FlowrouteMessagingLib\Controllers\MessagesController; use FlowrouteMessagingLib\Models\Message; #Pass your API credentials $controller_name = new MessagesController('Access Key','Secret Key'); #Create and Send a message $message_name = new Message('To', 'From', 'Message content'); $response = $controller->createMessage($message_name); #Get the MDR $response = $controller->getMessageLookup('recordID'); #Print the response print_r($response);
Run the file from the flowroute-messaging-php directory in a terminal window using the following command:
php <PHP file name>.php
This section describes the methods contained within the MessagesController. Methods are added to your PHP file between
$controller_name = new MessagesController('Access Key','Secret Key'); and
print_r($response). These two methods are:
The create and send message method is a two-step process. First you create the message content, and then you invoke the Controller to send the message.
Add the following two lines to your PHP file:
#Create and Send a message $message_name = new Message('To', 'From', 'Message content'); $response = $controller->createMessage($message_name);
The method takes the following parameters:
||True||string||The variable name identifying the message parameters. The variable can have any name, and there is no limit on the length. The name assigned here will then be passed in the
In this example, a message variable named
mymessage is created.
Message content are added, then
mymessage passed in
#Create and Send a message $mymessage = new Message('18444205700', '12062092844', 'Get some exercise!'); $response = $controller->createMessage($mymessage);
One of the following occurs:
print_r($response);was commented out or not added, the message is sent to the recipient, but no other confirmation is returned, or
print_r($response);was not commented out, a response message is returned containing the record ID:
( [data] => stdClass Object ( [id] => mdr1-6bdb954473d249308d43debd4735b493 ) )
idcan then be passed in the
getMessageLookupmethod to return details about the message.
If an error is encountered, an error message is returned. The message is not sent.
- ##### Error response
|No error code||HTTP Response Not OK||Typically this error might occur when the
getMessageLookup method is used to retrieve an MDR by passing the record identifier of a sent message. To get the message details, you must first modify the PHP file you created above.
Add the following line to your PHP file:
#Get the MDR $response = $controller->getMessageLookup('recordID');
Comment out the
createMessage lines as follows:
# $mymessage = new Message('18444205700', '12062092844', 'Get some exercise!'); # $response = $controller->createMessage($mymessage);
Important! If you do not comment out these lines, a new SMS will be sent, creating a new record ID.
The method is composed of the following parameter:
||True||string||The record identifier retrieved from the
#Get the MDR $response = $controller->getMessageLookup('mdr1-6bdb954473d249308d43debd4735b493');
Note: The following shows a sample formatted response and is intended only to more easily identify the fields returned in the response.
( [data] => stdClass Object ( [attributes] => stdClass Object ( [body] => Get some exercise! [direction] => outbound [timestamp] => 2016-05-20T17:07:46.322587+00:00 [amount_nanodollars] => 4000000 [from] => 12062092844 [message_encoding] => 0 [has_mms] => [to] => 18444205700 [amount_display] => $0.0040 [callback_url] => [message_type] => long-code ) [type] => message [id] => mdr1-6bdb954473d249308d43debd4735b493 ) )
Response message field descriptions
The following information is returned in the response message:
||Object composed of
||Object composed of the following:|
||Defines what the object is. Because SMS is the only supported object type, this field will always display
||The unique record identifier of a sent message, generated from a successful message creation.|
The following error can be returned:
|No code number||Response Not OK||This error is most commonly returned when the