Address Book & CSV Import
Managing contacts, grouping audiences, and ingesting frontend CSV lists.
Nyota SMS includes a native Address Book to store recipients, organize contacts into groups, and associate audiences with specific Organisational Units (OUs).
1. Contact Groups
Create and manage audience segments. Groups can be scoped to an OU or shared workspace-wide.
// Create a Contact Group
const group = await sms.groups.create({
name: "Retail VIP Customers",
description: "Customers who spent > KSh 50,000 in Q1",
ouId: "ou_sales_dept_123", // Optional OU scope
});
// List all groups with member counts
const groups = await sms.groups.list();
console.log(groups[0].memberCount); // e.g. 1,4502. Creating Contacts
Contacts are uniquely identified by (workspaceId, phone). Creating a contact that already exists updates their metadata automatically without throwing duplicate errors.
const contact = await sms.contacts.create({
phone: "0787654321",
firstName: "Alex",
lastName: "Kimani",
customData: {
loyalty_tier: "Platinum",
points_balance: 1420,
store_branch: "Westlands",
},
groupIds: [group.id],
});3. Bulk CSV Ingestion (Frontend Pattern)
For optimal user experience, parse CSV files directly in your Next.js frontend (using PapaParse), display a live column mapping preview to the user, and stream the clean JSON payload to Nyota:
// Frontend Next.js handler
const importResult = await sms.contacts.import({
groupIds: [group.id],
contacts: [
{
phone: "0787654321",
firstName: "Alex",
customData: { account_id: "ACC-1" },
},
{
phone: "0712345678",
firstName: "Beatrice",
customData: { account_id: "ACC-2" },
},
],
});
console.log(
`Imported: ${importResult.importedCount}, Invalid: ${importResult.invalidCount}`,
);The contacts.import endpoint accepts batches of up to 5,000 contacts per
request and performs atomic database upserts in sub-second time.