Skip to content

2. Parse SMS to FireFly‐III Transaction

Jump to bottom
Aft edited this page May 22, 2024 · 22 revisions

Not completed yet

Introduction to SMS Parser

The SMS Parser feature in smartMoney automates transaction entries in FireFly-III by:

  1. Retrieving new bank transaction SMS notifications from your mobile.
  2. Sending the SMS to smartMoney ParseSMS.
  3. Detecting if the SMS is an actual bank transaction and ignoring others.
  4. Extracting transaction information.
  5. Sending the transaction details to the FireFly-III API to record the transaction.

SMS2Transaction

How Does It Work?

Process Flow:

  1. Capture SMS:

    • An iOS receiver mobile app captures all incoming SMS on your mobile and sends them to your smartMoney server.

  2. Filter Bank Messages:

    • The smartMoney server filters only the bank messages based on the sender name specified in the .env file.

  3. Detect Transactions:

    • smartMoney checks if the SMS is a bank transaction or a non-transactional notification/advertisement.
    • If it is a transaction, it sends the SMS to the Parser class.

  4. Parse Transaction:

    • The Parser class (a PHP class) parses the SMS using regular expressions to extract transaction details such as amount, source, destination, currency, and type.
    • If your bank’s SMS format is not supported, you may need to create a custom Parser class. You can refer to existing Parser classes for guidance.

  5. Send to FireFly-III:

    • Once parsed, the transaction details are sent to the FireFly-III API to create the transaction entry.

  6. Handle Undetected Transactions:

    • If the Parser cannot detect transaction details, you can configure it to send the SMS to ChatGPT for information extraction. Note that this may incur ChatGPT usage costs.

  7. Categorize Transactions:

    • smartMoney attempts to categorize the transaction based on the destination (for withdrawals) or the source (for debits).
    • If it cannot determine the category, it can send the SMS to ChatGPT for categorization suggestions.

  8. Notifications:

    • Configure smartMoney to send push notifications to the web app on your mobile, informing you or others (like your family) about new transactions.

How to configure Parse SMS

If you want to enable SMS parsing for transactions, update the following settings in the .env file:

Enable/Disable SMS Parsing

PARSE_SMS_ENABLED=true

Configure SMS Senders

Provide a JSON configuration for the SMS senders: The json keys are the SMS Senders (if SMS sender name not in the list, it will be ignored), and the values are the class names under "app/parseSMS". You will need to create a class that will parse each bank, you can find multiple banks included under "app/parseSMS", copy any file and modify it as you can see fit to your bank SMS formats.

PARSE_SMS_SENDERS='{"saib":"parseSAIB","stcpay":"parseSTCPay"}'

In the above example:

  • If we receive SMS from sender saib, we will parse it using "parseSAIB" class (file located at app/parseSMS/Parsers"
  • If we receive SMS from sender stcpay, we will parse it using "parseSTCPay" class (file located at app/parseSMS/Parsers"
  • if we receive SMS from sender AMEX, we will simply ignore the SMS because sender AMEX is not configured in PARSE_SMS_SENDERS

Store Invalid and Valid SMS

Should we save invalid SMS (SMS that did not pass our initial validation or SMS that we are not able to parse as bank transaction)

PARSE_SMS_STORE_INVALID_SMS=true

Should we keep valid SMS in database even after parsing them?

PARSE_SMS_STORE_VALID_SMS=true

Minimum SMS Length for Valid Transactions

Any SMS message below this length will be considered as invalid bank transaction

PARSE_SMS_MIN_SMS_LENGTH=30

Auto-Detect Non-Transaction SMS

Before parsing any SMS, smartMoney can try to detect if this SMS is an actual Bank transaction or just a message from your bank for whatever reason, if the SMS message determined that it's not a valid message and PARSE_SMS_STORE_INVALID_SMS is true, it will be saved in database.

PARSE_SMS_AUTO_DETECT_NON_TRANSACTION_SMS=true

Fallback to OpenAI for Parsing

If your SMS parse class for this specific SMS sender were not able to parse the SMS message, would you like to send the SMS message to Azure OpenAI to parse it? Keep in mind, your BANK SMS Message with all the information will be sent to Azure OpenAI. you can enable/disable this also in Sender SMS parse class.

PARSE_SMS_FAILBACK_OPENAI=true

Use OpenAI for Category Detection

Would you like to use Azure OpenAI to determine the correct category for each transaction, smartMoney will first try to determine the category of every transaction based on the destination/source of the transaction, if it is not able to determine the category, it can ask Azure OpenAI. Keep in mind, your BANK SMS Message with all the information will be sent to Azure OpenAI.

PARSE_SMS_DETECT_CATEGORY_OPENAI=true

Clean SMS database

With time, you will find many SMSes stores in your database that are already processed, you can configure below variables to automatically delete SMSes from your database every week.

PARSE_SMS_CLEAN_PROCCESSED_SMS=true
PARSE_SMS_CLEAN_INVALID_SMS=true
PARSE_SMS_CLEAN_ERROR_SMS=true

How to create your bank SMS Parser

Creating a Custom Parser Class:

  • Guidelines and examples for creating a custom Parser class for unsupported banks.

Using ChatGPT for Parsing and Categorization:

  • How to enable and configure the ChatGPT integration for parsing and categorizing transactions.

Expense Account redirection

Mapping Account SMS Code to Account in FireFly-III

Different Account SMS Code for same account in FireFly-III

  • Supplementary Credit Cards:
    • If you use multiple supplementary credit cards, you can set up one account in FireFly-III and configure smartMoney to detect which card was used. This allows sending notifications to specific users while maintaining a single account in FireFly-III.

Create Alerts for new FireFly-III transactions

Known bugs

Clone this wiki locally