Uploading Files - Formatting and Functions

Introduction:

TextPower provides a way for you to manage the phone numbers of mobile devices subscribed ("opted in") to keywords established on your account using a simple file .CSV format.  Your file can take one of two formats:

1. Preformatted - all phone numbers must be in Column A.  Data of any kind in other columns will be treated as tags, not phone numbers to be opted in.  
2. Field Mapped using our Automated List Processing service - you can upload files of any configuration after subscribing to our service and submit a test file with a "map" indicating which columns contain phone numbers, which contain tags, and which columns to ignore.

Summary (if you read nothing else, read this):

• Files must be uploaded in a .CSV format.  
• A CR and LF character must be included at the end of each row.  When uploading a file that has been created, manipulated or opened in Excel and then saved as a .CSV the CR and LF characters are in place by default.  When uploading a list created by some other process, please make certain that each row ends in LF (line feed) character. 
• All columns and all rows - every piece of data - must be formatted as "Text" instead of as numbers.  
• If you are using the "Preformatted" option for uploading files all phone numbers must be in Column A; entries in all other columns are considered tags and if they are phone numbers they will not be opted in to receive messages.
• Punctuation is allowed in phone numbers (e.g., "888-555-1212" or "[phone]", etc.).
• Tags cannot contain spaces, symbols, or any other type of punctuation.
• Tags may contain letters or numbers or a mix of both.  Note that tags that BEGIN with a number will be stored and fully usable but will NOT be displayed in the list of groups when using AlertManager.  
• Individual tags may be up to 75 characters each.  All tags associated with one phone number can now be of unlimited cumulative length!
• We STRONGLY recommend that you define a test group.  The group should contain a few numbers of people to whose phones you can send test messages in order to insure that they are being properly formatted and sent.  You can do this easily by tagging some numbers with "TestGroup".  

Those are the essentials.  Read the details of this FAQ at least one time.  It will prevent errors, inform you of some useful features, avoid frustration, and in the long run save you time.  You'll be glad you did.  

Thank you.

---

Basic Functionality of the Upload/Sync Process

You can upload a list of numbers to your TextPower account so that you can send messages to that list or subsets of that list, called "groups."  Once you have uploaded these numbers they will be "opted in" and will remain in that state until either the mobile user or you take action on a number.  

The FCC has clarified that utilities in particular, as well as other groups, have the right to send text messages of an informational or emergency nature to numbers that have been provided to you in the normal course of business.  You can learn more about that by reading Big Win For Utilities: The TCPA Laws Clarified and learn how TextPower works to keep you in compliance with the TCPA regulations by reading Unique Service Helps Utilities With TCPA Compliance.

In addition to being able to send messages to numbers on an opt-in list, being on the opt-in list allows those numbers to send messages to you (such as an outage message for a utility or a request for a delayed appearance for a court).  These messages are known as "mobile-originated" messages or "MOs".  

The phone numbers on an opt-in list can have "tags" (such as a location ID) assigned to them and they can be part of a group (by substation, meter type, executive committee, etc.).  More information about both of these functions can be found further into this FAQ.

Note that the terms tag, send tag, group, and group name are all used interchangeably and refer to the same thing: a label that is applied to a mobile number that puts multiple numbers into a single "bucket" so that you can easily send to a subset of an entire list or for an account or an individual location ID that is used by an outage management system to determine which location an outage is being reported on.  Numbers do not have to be assigned to any group or can be assigned to one or multiple groups.  

Uploading these lists is simple.  Follow the structure described in this article and your file will be uploaded successfully, quickly, and reliably.  Once you create this file for uploading you will be able to maintain your own list of numbers and keep them synced with the numbers on the TextPower system, making a simple .CSV file the only thing you will need to manage the entire process.  

The first thing that happens when you upload a list is that each number will be checked to see which are mobile numbers and which are landlines.  The mobile numbers will be added to whichever one of the keywords that you specify when sending us the file to upload.  If you have not uploaded a file before you must use our "Communications Assurance Plan (CAP) file upload form" to send us files so that they are processed properly and promptly.  Files sent using regular email will not be processed; you will receive a response to your email directing you to use the form.  

The fundamental rules behind creating a file to use in the upload/sync process are:

Formatting of the file and file type:

• You may upload a file of up to 10MB.
• We provide a template for you to use and strongly recommend that you use it.  If you choose not to use our template (found HERE) we cannot assist you with troubleshooting any difficulties that occur during the file upload/sync process under our standard support.  Assistance with troubleshooting files other than those based on our template will incur an hourly fee.  
  • The template contains an example phone number - it is used as a placeholder and indication of where the first phone number should be placed.
  • The template contains labels called "Tag1", "Tag2", etc.  These are also examples to show where tags (also called "labels" or "groups") should be placed.  Change the ones you want to read whatever you prefer within the limits of what is allowed as a tag name (explained below) and delete the others.  
• All of the information in the spreadsheet, whether phone numbers or tags, must be in plain text.  Spreadsheet applications have built-in functions that manipulate data if left in a "number" format (such as changing lengthy numbers to scientific notation) that will cause the upload/sync to fail.  Just before saving the file either:
  • Use the keyboard command of Control-A (Windows) or Command-A (Macintosh) to select all of the cells in the spreadsheet.  
  • Click on the upper-most left corner of the spreadsheet, which will similarly select all of the cells in the spreadsheet.
• When all cells are selected, if you are using Excel go to the upper-most menu at the very top of your screen (not the menu items associated with that particular spreadsheet) and select Format>Cells…>Number>Category: and choose "Text" from the list shown in the window below the "Category:" label.  Click "OK" and that formatting box will close.
• Spreadsheets must be submitted in a .CSV format.  You may use any spreadsheet application to create and maintain the file but you must submit it in .CSV format.  Typically (and specifically in Excel) you would select the "Save As…" menu item from the top-most File menu.  In the "File Format" drop-down menu at the bottom of the window choose "Comma Separated Values (.csv) and navigate to where you want the file saved. 

Contents of the file:

• The recommended formatting is to place labels in Row 1 of the file so that you can designate various columns for specific purposes.  For example, Row 1, Column A might contain the label "Phone Numbers."  Row 1, Column B might contain the label "Location ID" or "Serv Loc" or "Meter Loc."  Row 1, Column C might have the label, "Substation number" or some other designator.  
  • All columns other than Column A can be designated with whatever labels you prefer.  
  • These labels are not stored anywhere on the TextPower system - they are only for your own use.  
• Column A must contain all of the phone numbers.  Any phone numbers erroneously placed in Columns B, C, D, etc., will not be entered into the database as phone numbers but rather as "tags" associated with the phone numbers in Column A.  Columns other than "A" are reserved for tags so any phone numbers in those columns will not be properly entered!
• You can add as many tags as you want within two limits:
  
  • Individual tags can be as long as 150 characters each.
  • All tags associated with one phone number may contain up to 2500 total characters cumulatively and can now be of unlimited cumulative length!
• Row 1 can be used either for labels or for data but not a mixture of both.  For example, if you put a phone number in Row 1, Column A, and then put labels in Columns B, C, D, etc., those labels will be assigned as tags to that phone number.   - use a descriptive term for the entries in this column.  It will not be stored anywhere on the TextPower system - this is for your use only.  
• You are also able to opt-out phone numbers using this process by prepending the number with a '-'.  The number appearing in the first column would look like this: -5102947763

About Tags (also called labels and can be groups of numbers):

• Tags can be unique to an individual number.  Many utilities in particular attach either a location ID, an account number, or a meter number to a cell phone number.  This facilitates the integration of outage reports with an outage management system (OMS) through one of TextPower's partners such as Milsoft, DataVoice, SienaTech, or PCS.  This way when a customer texts the word "out" into the system not only do we know which utility it is destined for (that's what the keywords are for) but the OMS will know which account/location/meter the outage is being reported on.  
• You may have as many tags as you wish, and assign mobile numbers to one group, multiple groups, or no groups at all.  
• There is no limit to the number of tags you may assign to a number.  There is also no limit to how many numbers may be assigned to one tag.  

Remember that you can assign any mobile number to one group, multiple groups, or no group by uploading a list of the mobile numbers with the groups assigned to them.  Group names can be as long as 150 characters but may NOT include spaces, symbols, or punctuation.  Here is a screenshot with helpful annotation: 

What if a number has been opted out?

When a mobile user opts out of receiving text messages by sending a "STOP" command ("QUIT" and "CANCEL" also work) it removes them from the opt-in list for that particular keyword and they cannot be opted back in by uploading a list with that number on it.

This is due to carrier regulations which state that once someone opts out of a keyword the only way for them to opt back in is to proactively do it themselves using one of the two methods we provide:

1. They can text the keyword into the shortcode directly from their mobile device.
2. They can opt-in by using the signup page or widget (for which we provide the code), which will also require them to receive a confirmation code sent to their device to assure that they are not spamming the system by entering numbers randomly without permission from the users.

If you are using one of TextPower's bulk upload mechanisms to upload a list of numbers and this opted-out number appears on the list it will not be added to the opt-in list for that keyword.

Suspend and Reactivate - What are they, how can they help you and how do they work?

These opt-out restrictions can, at times, be inconvenient to either you or the end-user, or both.  Your customers, for example, might have a second home or location for which they don't want to receive alerts year-round.  In that case, you will want to avoid opting a number out because the user will have to then opt their number back in using the process noted above, texting your keyword to your messaging number.

TextPower has created another way to approach these situations that is equally effective and meets all legal requirements for opt-outs.  Simply put, we have a way of allowing you to "suspend" a number, which is the functional equivalent of the number being opted out - it will no longer be sent any messages even though it technically remains opted in.  You can then "reactivate" that number, which is the functional equivalent of an opt-in, allowing messages to flow through to that number as if the user has opted in by texting your keyword to your messaging number.  

While there are several ways to accomplish this, including the use of our ManageOptin API call, the simplest way to use these functions is to put an "S" to suspend a number in front of that number in the file you are uploading.  For example, if you wanted to suspend the number 9876543210 you would have this in the column for your phone numbers:

S9876543210

To reactivate that number after it has been suspended, you simply use an "R" in front of that number in the file you are uploading, for example:

R9876543210

This "suspend" and "reactivate" capability allows you to accommodate the needs of your end-users without imposing the task on them of having to text your keyword into your messaging number every time they want to resume receiving messages.  

What about duplicated numbers?

The TextPower system will ignore duplicates… unless the group assignments are different.  If you have groups assigned to an email address (this applies to phone numbers for text messages, too) the system will assign whatever groups are indicated in the new spreadsheet.  If, for example, no groups are assigned in the current list and you upload an address and assign "GroupA" to it then the list will show that email address with "GroupA" assigned to it.  

Conversely, if you have "GroupA" assigned to an address and upload a new list and that same address does not have any groups assigned to it then it will leave the email address in place and leave the "GroupA" tag.  If you upload an email address that has "GroupB" assigned to it and "GroupA" is assigned to it in the existing list, that will be added and that email address will now show both "GroupA" and  "GroupB" assigned to it.

This provides a simple and fast way to manage your entire list of cell numbers and email addresses locally, on your own computer, by maintaining the entire list in a simple spreadsheet (as you already know it must be in comma-delimited format).  Then you can upload that list anytime you make modifications, on some schedule that works for you or just as needed.  No need to do any actual clicking, entering, or managing at all using the AlertManager application - it can all be easily maintained using a common spreadsheet format. 

Where do I go to upload the file?

The file upload/sync function is done through our FileUpload app which you will find at www.TextPower.com/FileUploader.  

• Login with the credentials for the keyword whose opt-in list you want to update.
• Click the "Choose File" button and navigate to your properly formatted .CSV file.  
• As a special option, you can choose to delete the entire list of opted-in numbers and upload a "fresh" list.  Note that this will completely wipe out all numbers and tags.  
• Click the "Upload File" button. 
• The TextPower system will inform you of the completion of your file's processing by sending notifications to the email address and the cell phone number on file. You will see both of those entries on the upload screen of the app.

Note that the file will be queued for uploading and will begin processing in the next available slot.  This may occur immediately or it may take some time depending on the load of the system.  Once the file processing begins the bulk import of the numbers and tags will occur very quickly.  The opt-in of the individual numbers will take longer as that is processor-intensive.  

The status of your upload and what the headings mean:

Once the upload/sync process is complete you can see the status of your upload by viewing the table on the Upload History page.  The various categories of that table are described here:

Guide to Column Headings Shown in Table After A Bulk Upload

Column Title	Meaning
Date	Start Date of this Bulk Upload
Total Rows in Batch	Total number of rows in the .csv file.
Distinct Numbers in Batch	How many numbers remained in the file after duplicates were removed?
Invalid Rows	The total number of lines in the spreadsheet that contained no data, incomplete data (not 10 digits) or obviously invalid phone numbers (e.g. 555-555-5555).
Non-Mobile Numbers	The number of lines in the spreadsheet that have a valid-looking phone number in them but are not cell numbers. These may be either landline numbers or unassigned numbers.
Mobile Numbers	The number of cell numbers found to be mobile numbers.
New Opted-In Mobile Numbers	The number of cell numbers that were newly opted in as a result of this upload.
Previously Opt-In Mobile Numbers (Batch)	The number of mobile numbers in this batch that were found to be already opted in.
New Opted-In Emails	The number of Email Addresses that were newly opted in as a result of this upload.
Previously Opted-In Emails (Batch)	The number of Email Addresses found to be already opted in.
Lookups	The total number of charged lookups that resulted from data in this upload. Lookups are necessary to find out if the number is a cell number.
Force Blocked (or ForceBlocked)	The number of phone numbers in the uploaded file that had been previously opted out and therefore are not allowed to be opted back in via a file upload (or any other method).

If this FAQ is not enough:

We do provide regular training sessions that all TextPower customers are invited to join; for our schedule email our support team. 

If you think it would be helpful if we could offer personalized training for your company; please contact us to arrange that (note that hourly charges may apply - we will advise you prior to setting up any personalized training). During this training, someone on our team will show you exactly how the process works and from that point forward you will be able to manage all of your mobile numbers in one spreadsheet and then upload it whenever you wish to the TextPower system to update your information.

Alternatively, you can call us at 818.222.8600 x2 (tech support) but for the fastest support response email our support team.