Overview

This guide will walk you through the process of integrating CalLab.ai with your ZIWO telephony system. This integration allows you to route calls through CalLab.ai for AI-powered call handling and analysis.

Prerequisites

Before starting this integration, ensure you have:

  • ZIWO Admin Access: You need administrator-level access to your ZIWO account
  • CalLab.ai Owner Account: You need owner-level access to your CalLab.ai account
  • Basic Understanding: Familiarity with telephony concepts (extensions, dial plans, SIP trunks)
  • Network Access: Ensure your ZIWO system can reach sip-pbx-qa.callab.ai on UDP port 5060

Make sure to test this integration in a non-production environment first to avoid disrupting your live phone operations.

Step 1: Create a Dial Plan in ZIWO

A dial plan is a set of rules that tells ZIWO how to handle incoming and outgoing calls. We’ll create a custom dial plan that routes calls to CalLab.ai.

1.1 Access the ZIWO Admin Panel

  1. Log in to ZIWO using your administrator credentials
  2. Navigate to Admin Menu: Look for the admin section in your ZIWO interface (usually in the top navigation or sidebar)
  3. Go to Channels: Click on “Channels” in the admin menu
  4. Select IVR & Dialplan: Choose “IVR & Dialplan” from the channels submenu

1.2 Create the New Dial Plan

  1. Click “Add New Plan”: Look for a button or link that says “Add New Plan” or similar
  2. Name Your Plan: Give your dial plan a descriptive name like “CalLab AI Integration” or “CalLab SIP Trunk”
  3. Copy the XML Configuration: Copy and paste the following XML code exactly as shown:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="dialplan" description="Dialplan">
    <context name="default">
      <extension name="stream_to_websocket">
        <condition field="destination_number" expression="^(\\d+)$">
            <!--<action application="answer"/> -->
            <action application="ring_ready"/> 
            <action application="set" data="absolute_codec_string=PCMU,PCMA"/>
            <action application="bridge" data="sofia/external/${destination_number}@sip-pbx-qa.callab.ai;transport=udp"/>
         </condition>
      </extension>
    </context>
  </section>
</document>

What this dial plan does:

  • ring_ready: Generates a ring tone for the caller
  • absolute_codec_string=PCMU,PCMA: Sets the audio codecs to use (standard telephony codecs)
  • bridge: Routes the call to CalLab.ai’s SIP server at sip-pbx-qa.callab.ai
  • transport=udp: Specifies UDP as the transport protocol
  1. Save the Dial Plan: Click “Save” or “Create” to save your new dial plan

1.3 Verify the Dial Plan Creation

  1. Check the List: Ensure your new dial plan appears in the list of available dial plans
  2. Note the Name: Remember the exact name you gave to the dial plan, as you’ll need it in the next step

Step 2: Create an Extension in ZIWO

An extension is a specific phone number or identifier within your ZIWO system that will use the dial plan we just created.

2.1 Navigate to Extensions

  1. Go to Extensions Menu: In your ZIWO admin panel, find and click on the “Extensions” menu
  2. Access Extension Management: Look for options to create or manage extensions

2.2 Create the Extension

  1. Click “Add Extension” or similar button to create a new extension
  2. Enter Extension Number: Type in your desired extension number (e.g., 1001, 2000, etc.)
    • Choose a number that doesn’t conflict with existing extensions
    • Make note of this number as you’ll need it later in CalLab.ai
  3. Configure Extension Settings:
    • Name: Give it a descriptive name like “CalLab AI Extension”
    • Type: Select the appropriate extension type (usually “Internal” or “SIP”)
  4. Select Dial Plan: From the dial plan dropdown, choose the dial plan you created in Step 1
    • Look for the name you gave it (e.g., “CalLab AI Integration”)

2.3 Save the Extension

  1. Review Settings: Double-check all your settings before saving
  2. Save Extension: Click “Save” or “Create” to create the extension
  3. Test Extension: If possible, test that the extension is working by calling it internally

Step 3: Configure CalLab.ai

Now that ZIWO is configured, you need to set up the corresponding configuration in CalLab.ai.

3.1 Log in to CalLab.ai

  1. Access CalLab.ai: Go to your CalLab.ai dashboard
  2. Log in as Owner: Make sure you’re logged in with an account that has owner-level permissions
  3. Verify Access: Ensure you can see administrative settings and phone number management

3.2 Add ZIWO Phone Number

  1. Navigate to Phone Numbers: Look for “Phone Numbers” in your CalLab.ai navigation menu
  2. Click “Add Phone”: Find and click the button to add a new phone number
  3. Select ZIWO: Choose “ZIWO” from the list of telephony providers
  4. Enter Extension: In the extension field, enter the exact extension number you configured in ZIWO (from Step 2.2)
    • This must match exactly what you set in ZIWO
  5. Configure Additional Settings: Fill in any other required fields such as:
    • Display name for the phone number
    • Call routing preferences
    • AI assistant settings

3.3 Save and Activate

  1. Save Configuration: Save your ZIWO phone number configuration
  2. Activate: Make sure the phone number is set to active/enabled
  3. Test Configuration: Verify that the phone number appears in your active phone numbers list

Step 4: Testing the Integration

4.1 Initial Test

  1. Make a Test Call: Call the extension you created in ZIWO
  2. Listen for Ring: You should hear the phone ringing
  3. Check Call Routing: The call should be routed to CalLab.ai
  4. Verify AI Response: CalLab.ai should answer and engage with the caller

4.2 Verification Checklist

  • Extension rings when called
  • Call is successfully routed to CalLab.ai
  • CalLab.ai AI assistant responds appropriately
  • Call quality is acceptable (clear audio, no delays)
  • Call logs appear in both ZIWO and CalLab.ai dashboards

Troubleshooting

Common Issues and Solutions

Issue: Extension doesn’t ring

  • Solution: Check that the extension number is correct and the dial plan is properly assigned
  • Check: Verify the extension is active in ZIWO

Issue: Call doesn’t reach CalLab.ai

  • Solution: Verify the dial plan XML is exactly as provided
  • Check: Ensure network connectivity to sip-pbx-qa.callab.ai
  • Check: Confirm UDP port 5060 is not blocked by firewalls

Issue: Poor call quality or audio issues

  • Solution: Check network bandwidth and stability
  • Check: Verify codec settings (PCMU, PCMA should be supported)

Issue: CalLab.ai doesn’t recognize the phone number

  • Solution: Double-check that the extension number in CalLab.ai exactly matches the one in ZIWO
  • Check: Ensure the phone number is active in CalLab.ai

Getting Help

If you continue to experience issues:

  1. Check Logs: Review call logs in both ZIWO and CalLab.ai for error messages
  2. Network Diagnostics: Test connectivity to sip-pbx-qa.callab.ai
  3. Contact Support: Reach out to CalLab.ai support with:
    • Your ZIWO extension number
    • Error messages from logs
    • Description of the issue and when it occurs

Next Steps

After successful integration:

  1. Configure AI Settings: Customize your AI assistant’s behavior in CalLab.ai
  2. Set Up Call Routing: Configure how calls should be handled (forwarding, voicemail, etc.)
  3. Monitor Performance: Use CalLab.ai analytics to track call performance and AI effectiveness
  4. Scale Up: Apply this configuration to additional extensions as needed

Consider setting up multiple extensions for different departments or use cases to better organize your call handling and AI assistant configurations.