<commit_before># flowroute-messaging-ruby

**flowroute-messaging-ruby** is a Ruby SDK that provides methods to send an outbound SMS from a Flowroute phone number and also to retrieve a Message Detail Records (MDR). These methods use **v2** (version 2) of the [Flowroute](https://www.flowroute.com) API.

These methods can be used to accomplish the following:

*	Send an outbound SMS
*	Retrieve a message detail record (MDR)

**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](https://developer.flowroute.com/docs/lookup-a-set-of-messages) on the Flowroute Developer Portal.

## Documentation 
The full documentation for v2 of the Flowroute API is available [here](https://developer.flowroute.com/v2.0/docs).

##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](https://manage.flowroute.com/accounts/preferences/api/) portal. If you do not have API credentials, contact <mailto:<EMAIL>>.

### 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](https://manage.flowroute.com/accounts/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*. 

## Install the required libraries

> **Note:** You must be connected to the Internet in order to install the required libraries.

The SDK uses the UniRest Ruby library, which must be installed before you can use the SDK. 

1. Open a terminal session. 

2. If needed, create a parent directory folder where you want to install the SDK.
 
3. Go to the newly created folder, and run the following:

 	`git clone https://github.com/flowroute/flowroute-messaging-ruby.git`
 	
 	The `git clone` command clones the **flowroute-messaging-ruby** repository as a sub directory within the parent folder.
 	
4.	Change directories to the newly created **flowroute-messaging-ruby** directory.

5.	Run the following:

		gem build flowroute_messaging.gemspec
		gem install flowroute_messaging-1.0.gem

6.	Import the SDK.
  
## Create a script to import the SDK and send a message

Importing the SDK requires that you run commands either by creating and running a script or through the shell. The following instructions describe importing the SDK and running the `messages_controller` by creating and running a script.

>**Note:** The following steps describe creating a new Ruby script. However, a demo script, **demo_send.rb**, was installed when the the libraries installed. This file contains the required lines that only need to be modified with your credentials and details for the message to send. If you want to use this script, modify the fields as described below, then run the script from the command line.  

1.	Using a code text editor — for example, *Sublime Text* — create a new file.

2.	Add the following line to the top of the file:

		#Require Flowroute Messagine
		require 'flowroute_messaging'
		
3.	Next, add the lines to instantiate the controller:

		#Pass your API credentials
		ctl = FlowrouteMessaging::MessagesController.new('YOUR_API_KEY', 'YOUR_API_SECRET_KEY')   

4.	Replace `YOUR_API_KEY` and `YOUR_API_SECRET_KEY` with your own Access Key and Secret Key.

5.	Add the [message_controller](#controller) methods.

6.	Save the file in the top-level **flowroute-messaging-ruby** directory with a **.rb** extension. For this example, the file is named **createmsg.rb**.

7.	From the **flowroute-messaging-ruby** directory in a terminal window, run the following to invoke the methods within the file:

		ruby createmsg.rb
		
###Example Ruby file
	
The following shows an example file, **createmsg.rb**, that contains all Controller methods:
	
		#Import the Flowroute Messaging SDK (Ruby)
		require 'flowroute_messaging'

		#Instantiate the controller
		ctl = FlowrouteMessaging::MessagesController.new('12345678', 'm8axLA45yds7123488aOQ7BshaADg6vr')

		#Create, send and print the message
		msg = FlowrouteMessaging::Message.new(to='15305557784', from='18444205700', content='You're obviously not a golfer.')
		ctl.create_message(msg)
		print ctl.create_message(msg)	


## messages_controller<a name=controller></a>

The `messages_controller` contains the methods required to send outbound SMS texts and to retrieve MDRs:

*	[`create_message`](#createmessage)— used to send outbound messages from an SMS-enabled Flowroute number.
* 	[`get_message_lookup`](#getmessage)— used to retrieve the MDR for a specified message.

### `create_message`<a name=createmessage></a>

The `create_message` function is used to send outbound messages from an SMS-enabled Flowroute number. 

#### Usage

Add the following lines to your Ruby file to create the message, send the message, and then print the message record identifier to the screen:<commit_msg>added error response msgs to readme.md<commit_after># flowroute-messaging-ruby

**flowroute-messaging-ruby** is a Ruby SDK that provides methods to send an outbound SMS from a Flowroute phone number and also to retrieve a Message Detail Records (MDR). These methods use **v2** (version 2) of the [Flowroute](https://www.flowroute.com) API.

These methods can be used to accomplish the following:

*	Send an outbound SMS
*	Retrieve a message detail record (MDR)

**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](https://developer.flowroute.com/docs/lookup-a-set-of-messages) on the Flowroute Developer Portal.

## Documentation 
The full documentation for v2 of the Flowroute API is available [here](https://developer.flowroute.com/v2.0/docs).

##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](https://manage.flowroute.com/accounts/preferences/api/) portal. If you do not have API credentials, contact <mailto:<EMAIL>>.

### 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](https://manage.flowroute.com/accounts/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*. 

## Install the required libraries

> **Note:** You must be connected to the Internet in order to install the required libraries.

The SDK uses the UniRest Ruby library, which must be installed before you can use the SDK. 

1. Open a terminal session. 

2. If needed, create a parent directory folder where you want to install the SDK.
 
3. Go to the newly created folder, and run the following:

 	`git clone https://github.com/flowroute/flowroute-messaging-ruby.git`
 	
 	The `git clone` command clones the **flowroute-messaging-ruby** repository as a sub directory within the parent folder.
 	
4.	Change directories to the newly created **flowroute-messaging-ruby** directory.

5.	Run the following:

		gem build flowroute_messaging.gemspec
		gem install flowroute_messaging-1.0.gem

6.	Import the SDK.

 
## Create a script to import the SDK

Importing the SDK requires that you run commands either by creating and running a script or through the shell. The following instructions describe importing the SDK and running the `messages_controller` by creating and running a script.

>**Note:** The following steps describe creating a new Ruby script. However, a demo script, **demo_send.rb**, was installed when the the libraries installed. This file contains the required lines that only need to be modified with your credentials and details for the message to send. If you want to use this script, modify the fields as described below, then run the script from the command line.  

1.	Using a code text editor — for example, *Sublime Text* — create a new file.

2.	Add the following Ruby `require` line at the top of the file:

		#Require Flowroute Messaging
		require 'flowroute_messaging'
		
3.	Next, add the lines to pass your API credentials to the Controller:

		#Pass your API credentials
		ctl = FlowrouteMessaging::MessagesController.new('YOUR_API_KEY', 'YOUR_API_SECRET_KEY')   

4.	Replace `YOUR_API_KEY` and `YOUR_API_SECRET_KEY` with your own Access Key and Secret Key.

5.	Add the [MessagesController](#controller) methods.

6.	Save the file in the top-level **flowroute-messaging-ruby** directory with a **.rb** extension. For this example, the file is named **createmsg.rb**.

7.	From the **flowroute-messaging-ruby** directory in a terminal window, run the following to invoke the methods within the file:

		ruby createmsg.rb
		
### Example Ruby file
	
The following shows an example file, **createmsg.rb**, that contains all Controller methods:
	
	#Require Flowroute Messaging
	require 'flowroute_messaging'

	#Pass your API credentials
	ctl = FlowrouteMessaging::MessagesController.new('12345678', 'm8axLA45yds7123488aOQ7BshaADg6vr')

	#Create, send and print the message
	msg = FlowrouteMessaging::Message.new(to='To Phone Number', from='From Phone Number', content='Message content')
	ctl.create_message(msg)
	print ctl.create_message(msg)	
		
	#Get the MDR
	recID = 'recordIdentifier'
	print ctl.get_message_lookup(recID))
		
## MessagesController<a name=controller></a>

The `MessagesController` contains the methods required to send outbound SMS texts and to retrieve MDRs:

*	[`create_message`](#createmessage)— used to send outbound messages from an SMS-enabled Flowroute number.
* 	[`get_message_lookup`](#getmessage)— used to retrieve the MDR for a specified message.

### `create_message`<a name=createmessage></a>

The `create_message` function is used to send outbound messages from an SMS-enabled Flowroute number. 

#### Usage

Add the following lines to your Ruby file to create the message, send the message, and then print the message record identifier to the screen:
{'fraction_non_alphanumeric': 0.0746461936916104, 'fraction_numerical': 0.009434834890389418, 'mean_word_length': 4.544615384615384, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 21, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '389632', 'n_tokens_mistral': 3138, 'n_tokens_neox': 2897, 'n_words': 1444}