Mobile Commons: Mobile Commons Glossary

Company: The customer's name, such as ABC Company. This is the company name of associated with your platform account. You can find this at the top of your platform account next to the Upland Mobile Commons Logo.

Short Code: The 5 or 6-digit number the company uses to send/receive SMS (text) and MMS (image) messages (e.g. 877877, 69866).  Mobile Commons customers can utilize a shared short code or a dedicated short code. A dedicated short code means you are the only customer using that short code and has additional costs associated with it. Keywords are unique to a short code, so if another customer already is using a keyword on your shared short code you can not use that same keyword. Short codes (both shared and dedicated) are also unique by country. Your short code will not work for numbers outside of the US. Mobile Commons can help you purchase and use short codes for other countries. Just email us at mc_support@uplandsoftware.com to find out how!

Keyword: A Keyword is a word that a user texts in to your short code to subscribe to your mobile list. Keywords comprise between 2 and 20 alphanumeric characters.  Read more about keywords here.

Phone: a mobile phone number (10 digits) and carrier; each phone number that interacts with Mobile Commons has a profile. Phone number is the unique identifier for profiles in Mobile Commons.

Profile: A database record representing a participant. Phone number is the primary key. Each profile can store name, email, address, and custom fields. Please see our article on profiles. 

Character Count: all standard SMS messages and ALL STOP & HELP messages must be 160 characters or less. This character count includes spaces, a line break counts as a space (hitting enter). Please note, if you are using special characters, including many foreign language characters your allowable character count will drop. Please be sure to read our article on this topic. If your message goes over the standard 160 character count it will turn your message into a multi-part message.

If you are copying and pasting from a word processing or other software program your paste may include invisible characters that add extra characters to your message when pasted and may put your message over the standard character count and into multi-part messages. Be careful to copy and paste from plain text only and always double check the character count in the platform and send a test message to yourself. 

Below is an example of a the character count. This message has 65 characters left and will be sent as an SMS. If the author continued to type and added more than 65 additional characters the message would automatically become a multi-part message.

Active Campaign: A collection of related opt-in paths and text messages. Read more about campaigns here.

Opt-In Path: how someone subscribes to your campaign. You can set up a keyword opt-in path, which enables subscriptions via texting in a keyword to an opt-in path, or a non-keyword opt-in path which enables subscriptions via a web form, CRM sync or any other non-keyword method. Read more about opt-in paths here.

Subscription: When a profile is opted-in to a campaign, the Mobile Commons platform creates an active subscription record. This subscription record manages which text messages the subscriber should receive and from which campaign. Opting out will end the subscription. Opting in again creates a new subscription record. Only a single active subscription is allowed per profile per campaign at a time.

"Incoming Text Message" or "MO" ("Mobile Originated") or "Message Received": Text messages sent FROM a phone/handset TO Mobile Commons. It has a phone/profile, a timestamp, and a body. Mobile Commons will classify it based on our message processing rules and (optionally) send a reply outgoing text message.

"Outgoing Text Message" or "MT"("Mobile Terminated") or "Message Sent": Text message sent FROM Mobile Commons TO a phone/handset. 

Custom Field: a profile’s value for a given custom field (e.g. Quit Date = Jan 1, 2014).

Custom Field Type: a company can have many custom fields with specific data types e.g. string, number, gender, etc

Table: The text message content scheduled to go out for a given campaign.

Row: Each row in a table contains the message body to send out, and a day offset from the target date and time of day. Note that the row doesn’t contain just the body, but a link to a Message List.

Message: The “template” used to generate an outgoing text message. It contains the body to  generate, the type of message (e.g. info request), and info being requested (e.g. age). In conversations with multiple 2-way text message, it also contains the Position in the message list. 

Message List: An ordered collection of Messages. Each Opt-in Path and Row contains a link to a message list.

Custom Field Definitions

The following custom field data types are supported. All fields may be blank. See more here: Custom Fields

Text: Free text up to 2,550 characters
Date: In YYYY-MM-DD format
Gender: Text field. Possible values: male, female, nonbinary, prefer not to say
Identity: Text field. Possible values: transgender, cisgender, prefer not to say
Number: Positive or negative numbers. Can be integers or decimal.
Age: Numbers between 0 and 120.
Yes or No: Text field. Possible values: Yes, No
 

Mobile Common Export Data Formats & Transformations

Profile Export: 

phone_number
Data Type: Text Values: 11 digit phone number OR de-identified phone number in PRxxxxxxxxx format

email
Data Type: Text Values: Valid email according to RFC0822

first_name
Data Type: Text Description: First Name

last_name
Data Type: Text Description: Last Name

status
Data Type: Text Description: Opt-in status Values: Active Subscriber, No Subscriptions, Undeliverable, Never Seen Before description: Data Type: Text Description: DEPRECATED. This is a legacy column. Prefer opt_out_source column instead

street1
Data Type: Text Description: Address, Street 1

street2
Data Type: Text Description: Address, Street 2

city
Data Type: Text Description: Address, City

state
Data Type: Text Description: Address, State

postal_code
Data Type: Text Description: Address, Postal Code

country
Data Type: Text Description: Address, Country

congressional_district
Data Type: Text Description: Congressional District for political organizations.

latitude
Data Type: Decimal Description: Latitude of geocoded address

longitude
Data Type: Decimal Description: Longitude of geocoded address

geocoded_city
Data Type: Text Description: Result of passing user-entered address through a geocoder, City

geocoded_state
Data Type: Text Description: Result of passing user-entered address through a geocoder, State

geocoded_postal_code
Data Type: Text Description: Result of passing user-entered address through a geocoder, Postal Code

geocoded_country
Data Type: Text Description: Result of passing user-entered address through a geocoder, Country

carrier_name
Data Type: Text Description: Human friendly name of phone's carrier (operator). There are hundreds of carriers in the US.

created_at
Data Type: Timestamp Description: When the profile was created in Mobile Commons database

source_type
Data Type: Text Description: How this profile was originally added to Mobile Commons database Values: Broadcast, Campaign, Report, Data Sync, Tell A Friend, Uploaded Group, Uploaded Group, mConnect, Keyword, mData, Mobile Giving, Opt-In Path, API

source_name
Data Type: Text Description: The name of the profile's source, as configured in your Mobile Commons instance.

opted_out_at
Data Type: Timestamp Description: When the profile was opted out of Mobile Commons

opt_out_source
Data Type: Text Description: Reason for opt-out Values: Web form opt-out, Texted a STOP word, Manual opt-out, Opt-out from inbox, Opt-out from profile, Opt-out via CSV upload, Opt-out from API, Subscription declined, Phone was deactivated, Hard bounce, Campaign Ended, Last subscription was opted out, Opt-out, Subscription expired, No confirmed subscriptions, Duplicate subscription, User moved to another campaign, Did not match criteria for smart campaign

Accept Terms
Data Type: Boolean Description: User accepted Terms of Service Values: Yes, No

Web Enabled phone
Data Type: Boolean Description: Can user access the internet on their phone Values: Yes, No Inbox and Outbox Exports: Note: Most Profile Columns are duplicated in this export for convenience. They are listed at the end and in the same formats as above

direction
Data Type: Text Description: Was this text message sent from Mobile Commons to handset, or received by Mobile Commons Values: sent, received

when
Data Type: Text Description: When was this text message sent or received

body
Data Type: Text Description: Body of the text message. 160 characters or fewer

message_type
Data Type: Text Description: Mobile Commons classification about what type of text message this is

Value for Sent Messages, with description:

• Duplicate_subscription_notification: User opted in again, we responded that they were already oped in
• ftaf_opt_in_request: Tell-a-Friend, Beta invitation
• ftaf_request: Tell-a-Friend, Alpha asked to respond with friends' numbers
• help_response: Response to user texting HELP
• info_request: Request for information e.g. age, gender, quit date
• mdata_request: Replies to this message will get sent to mData
• opt_in_confirmation: Double opt-in request
• opt_out_receipt: Response to user texting STOP
• persistent_mdata_response: Replies to this message will get sent to mData again

Value for Received Messages, with description:

• duplicate_opt_in: Opted in again, without opt-in
• help_request: User texted HELP
• info_response: User relied to request for information with a recognized format
• invalid_info_response: User relied to request for information with an unrecognized format
• mdata_query: User texted mData
• opt_in: User opted in
• opt_in_confirmation: User replied "Y" to double opt-in confirmation message
• opt_in_declination: User did not reply "Y" to double opt-in confirmation message
• opt_out: User opted out
• reactivation: User replied opted out
• reply: Unexpected user reply to a message
• simultaneous: We got 2 simultaneous messages, usually duplicate from carrier. Only one was processed.
• unknown: User sent unrecognized keyword
• invalid_ftaf_response: Tell-a-friend, alpha replied with invalid phone number. No beta invited
• ftaf_opt_in_confirmation: Tell-a-friend, beta accepted invitation
• ftaf_opt_in_declination: Tell-a-friend, beta declined invitation
• ftaf_response: Tell-a-friend, alpha replied with valid phone number to invite beta

status Data Type: Text Description: These are English descriptions of the above message_type column

Value for Received Messages:

• Did not match any keywords, using default for this short code
• Found an outgoing info-request and the response body matched the request
• Found an outgoing info-request, but the response did not contain requested information
• Found an outgoing Tell a Friend request and the response body matched the request
• Found an outgoing Tell a Friend request, but the response did not contain any phone numbers
• Matched on keyword
• Matched on mdata keyword
• Matched on reactivation request but already subscribed
• Opt-out
• Subscriber confirmed opt-in
• Subscriber confirmed opt-in from Tell a Friend
• This message arrived at the same time as another
• This was a reply to a persistent mData
• This was a reply to an mData request
• This was a reply to an outgoing text message
• Unable to d