SMS Merge Tags & Dynamic CSV Audience Ingestion

Personalized SMS messages (e.g., addressing customers by their first name or referencing their specific account balance) achieve up to 4x higher engagement and click-through rates compared to generic mass blasts.

Nyota SMS includes a high-performance In-Browser CSV Sanitizer and a dynamic Merge Templating Engine that lets you drag-and-drop spreadsheets of up to 50,000 contacts and broadcast tailored messages in minutes.

1. How Ingestion & Merge Templating Work Under the Hood

When you upload an audience spreadsheet, Nyota processes your data in two phases:

TEXT

1. BROWSER-SIDE CSV SANITIZATION (Client-Side Privacy)
    User drops .csv file -> Browser parses rows locally (0 data sent to server yet)
    - Normalizes local phone numbers (0712..., 0110..., +254...) -> E.164 (254712345678).
    - Removes duplicates & flags malformed numbers.
                         │
                         ▼
 2. DYNAMIC TEMPLATE MERGING (Local Outbox)
    Template: "Hello {{firstName}}, your loan balance is KSh {{balance}}."
    -> System renders personalized text for every recipient row
    -> Generates individual queued records in sms.sms_messages.
                         │
                         ▼
 3. LIVE COMPOSER PREVIEW
    Admin views real-time rendered previews of the first 3 recipients
    before confirming dispatch.

2. Formatting Your CSV Spreadsheet

For seamless ingestion, format your spreadsheet with clear column headers in the first row. Column names automatically become your available Merge Tags:

phone	firstName	lastName	balance	dueDate
`0712345678`	John	Doe	1,500	25th Sep
`0110000000`	Mary	Wanjiku	3,200	28th Sep
`254722000000`	David

Export or save your spreadsheet as a standard CSV (Comma Delimited) file (.csv).

3. Available Merge Tags & Template Syntax

In your message composer, wrap column names in double curly braces {{tag}}:

{{firstName}} →→ Inserts recipient's first name (e.g., John)
{{lastName}} →→ Inserts recipient's last name (e.g., Doe)
{{balance}} →→ Inserts custom financial balance (e.g., 1,500)
{{dueDate}} →→ Inserts custom date (e.g., 25th Sep)

Template Example:

"Hello {{firstName}}, your Nyota Drive storage renews on {{dueDate}}. Your current balance is KSh {{balance}}. Visit accounts.nyotaimara.com to manage your plan."

4. Step-by-Step: Uploading and Dispatching a Personalized Campaign

Log in to sms.nyotaimara.com.
Go to Contacts & Audiences in the left sidebar (/contacts).
Click "Import Contacts" and select or create a Contact Group (e.g., September Customers).
Drag and drop your .csv spreadsheet.
The in-browser sanitizer will automatically:
- Convert local Kenyan numbers (07... and 01...) to international 254... format.
- Filter out invalid rows and duplicates.
Navigate to Campaigns
→→
"New Broadcast Campaign".
Select your Contact Group and compose your message template using merge tags.
Review the Live Recipient Previews to verify variable substitution.
Click "Schedule & Launch Broadcast".

5. Common Pitfalls & How to Troubleshoot

Pitfall A: "Message segment overflow caused by long recipient names."

The Cause: Your template was 155 characters long in GSM-7. For a recipient with a long name (e.g., Alexander-Christopher), the rendered text expanded to 172 characters, pushing that single message into 2 segments (2 units).
The Resolution: Leave a 10 to 15 character buffer in your message copy when using dynamic name fields so that long names do not cross the 160-character segment limit.

Pitfall B: "Phone numbers showing as scientific notation in Excel (2.54712E+11)."

The Cause: Microsoft Excel automatically formats long numeric strings as scientific notation.
The Resolution: Nyota’s browser-side sanitizer automatically repairs scientific notation on upload. Alternatively, format the phone column in Excel as "Text" before saving as CSV.