How to Build a Multi-Tenant VoIP Platform: Architecture Guide for SaaS Startups

<!-- Each tenant gets their own XML directory file -->
<!-- Generated by the provisioning API when a tenant is created -->

<include>
  <domain name="tenant123.yourplatform.com">
    <params>
      <!-- Tenant-specific dialplan context -->
      <param name="dial-string"
             value="{^^:sip_invite_domain=${dialed_domain}:presence_id=${dialed_user}@${dialed_domain}}
                    ${sofia_contact(*/${dialed_user}@${dialed_domain})}"/>
    </params>
    <variables>
      <variable name="record_stereo" value="true"/>
      <variable name="default_gateway" value="tenant123-pstn"/>
      <!-- Per-tenant call recording path -->
      <variable name="recording_path" value="/recordings/tenant123/"/>
    </variables>
    <groups>
      <group name="default">
        <users>
          <!-- Users are dynamically loaded from PostgreSQL via mod_xml_curl -->
          <!-- No need to list each user in static XML -->
        </users>
      </group>
    </groups>
  </domain>
</include>

<configuration name="xml_curl.conf" description="cURL XML Gateway">
  <bindings>
    <!-- Directory binding: fetch user auth from your provisioning API -->
    <binding name="directory">
      <param name="gateway-url"
             value="https://api.yourplatform.com/fs/directory"/>
      <param name="bindings" value="directory"/>
      <!-- Pass FreeSWITCH's request params to your API -->
    </binding>

    <!-- Dialplan binding: fetch tenant dialplan from your API -->
    <binding name="dialplan">
      <param name="gateway-url"
             value="https://api.yourplatform.com/fs/dialplan"/>
      <param name="bindings" value="dialplan"/>
    </binding>
  </bindings>
</configuration>

const express = require('express');
const router = express.Router();

// POST /api/tenants — provision a new tenant
router.post('/tenants', async (req, res) => {
  const { companyName, adminEmail, plan, didAreaCode } = req.body;

  try {
    // 1. Generate tenant ID and subdomain
    const tenantId = generateSlug(companyName);  // e.g., "acme-corp"
    const domain = `${tenantId}.yourplatform.com`;

    // 2. Provision DID from SIP trunk provider API
    const did = await sipTrunkProvider.purchaseDID({
      areaCode: didAreaCode,
      routeTo: `sip:${tenantId}@${process.env.FREESWITCH_IP}`,
    });

    // 3. Create tenant record in PostgreSQL
    const tenant = await db.tenants.create({
      id: tenantId,
      company_name: companyName,
      domain,
      did_number: did.number,
      plan,
      status: 'provisioning',
    });

    // 4. Generate FreeSWITCH domain XML file
    await generateFreeSwitchDomainXML(tenantId, domain);

    // 5. Create SIP gateway for tenant's PSTN outbound route
    await freeswitchESL.api(
      `sofia profile internal rescan`
    );

    // 6. Create default admin extension (1000)
    const adminExt = await provisionExtension({
      tenantId,
      extension: '1000',
      name: companyName + ' Admin',
      email: adminEmail,
      password: generatePassword(),
    });

    // 7. Set up billing rate table for plan
    await billingEngine.createTenantRatePlan(tenantId, plan);

    // 8. Send welcome email with SIP credentials
    await emailService.sendWelcome({
      to: adminEmail,
      tenantId,
      domain,
      extension: '1000',
      sipPassword: adminExt.sipPassword,
      did: did.number,
    });

    // 9. Update tenant status to active
    await db.tenants.update(tenantId, { status: 'active' });

    res.json({
      success: true,
      tenantId,
      domain,
      did: did.number,
      adminPortal: `https://${domain}/admin`,
    });

  } catch (error) {
    // Rollback provisioned resources on failure
    await rollbackTenantProvisioning(tenantId);
    res.status(500).json({ error: error.message });
  }
});