Skip to main content

Smokeball Integration

This integration connects your Vodia PBX with Smokeball, a legal practice management platform. The integration provides real-time caller identification with screen pop functionality, displaying contact information and direct links to client records in Smokeball when calls arrive. It supports multiple regions (United States, Australia, and United Kingdom) with region-specific authentication and API endpoints.

tip

It is important that telephone numbers in Smokeball are stored in the format that the PBX uses. For US numbers this format is a 10-digit format (for example, 6173998147). This is because telephone numbers need to match exactly in Smokeball.

tip

Enhance your experience by using this integration with our click-to-dial and web portal features.

Requirements​

  • Active Smokeball Account: Valid Smokeball subscription with API access
  • Regional Configuration: Select the appropriate region (US, Australia, or UK) that matches your Smokeball account
  • OAuth Authentication: Each user must authorize the integration through Smokeball's OAuth flow
  • Email Matching: To ensure proper functionality, the email address associated with the extension in Vodia PBX should match the user's email address in Smokeball
  • Contact Phone Numbers: Phone numbers must be stored in Smokeball's contact records for lookup to work

Integration Setup​

Domain-Level Configuration​

  • In the Tenant, under Advanced->CRM Integration, go to Smokeball:
    • Region: Select your Smokeball region (USA, Australia, or UK)
    • Staging: Select "Yes" only if using Smokeball staging environment (typically "No" for production)
    • Scope: Set the scope for the integrations i.e. all accounts or group of accounts
    • Save the settings

User-Level Authentication​

Each user who wants to receive caller identification must pair their account:

  • Navigate to the user's CRM settings page

  • Under Smokeball integration:

    • Check the Status indicator (red X = not paired, green checkmark = paired)
    • Click the Pair button to begin OAuth authentication
    • A new window will open for Smokeball login and authorization
    • After successful authorization, the window will close automatically
    • Verify the status indicator turns green

    smokeball-user.png

  • To unpair an account, click the Unpair button

note

Each user must complete the pairing process individually. Domain-level configuration alone is not sufficient for the integration to function.

Integration Features​

  • Real-Time Contact Identification: Displays caller information instantly when calls arrive
  • Screen Pop with Direct Links: Shows contact name and clickable link to the contact's record in Smokeball in Vodia's Agent web app.
  • Inbound and Outbound Support: Identifies contacts for both incoming and outgoing calls
  • Multi-Region Support: Seamlessly works with Smokeball US, Australia, and UK instances
  • OAuth Security: Secure token-based authentication per user
  • Internal Call Filtering: Automatically ignores extension-to-extension calls and star codes
  • Staging Environment Support: Option to connect to Smokeball staging servers for testing

How It Works​

Call Flow​

  1. Incoming Call Arrives:

    • When a call enters the ringing state, the integration automatically searches Smokeball
    • Searches are performed using the caller's phone number
    • Search checks Smokeball contacts for matching phone numbers

  2. Contact Found:

    • If a match is found, a caller identification popup appears on the agent's Vodia web app
    • The popup displays:
      • Contact's full name (first name + last name)
      • Clickable link to the contact's Smokeball profile
      • Link format: https://rc-app.smokeball.com.au/#/billing/view-contact/{id}/details

  3. Contact Not Found:

    • If no matching contact exists in Smokeball, no popup is displayed
    • The call proceeds normally without caller identification

  4. Outbound Calls:

    • When an agent places an outbound call, the system searches for the dialed number
    • If found, displays who the agent is calling before the call connects

Call Filtering​

The integration intelligently filters calls to prevent unnecessary API requests:

  • Internal Calls: Extension-to-extension calls are ignored
  • Star Codes: Calls to feature codes (starting with *) are not processed
  • Invalid States: Only processes calls in ringing, connected, or terminated states

Data Privacy​

  • Contact lookups are performed in real-time and not stored by the PBX
  • OAuth tokens are securely stored per user and encrypted
  • API communications use HTTPS with secure authentication
  • Contact information is only shared between your Vodia PBX and your Smokeball account
  • Users can unpair their accounts at any time to revoke access

Troubleshooting​

Status shows red X after pairing:

  • Wait 3-5 seconds for the status to refresh
  • Refresh the page manually
  • Verify the OAuth popup completed successfully

No caller identification appearing:

  • Verify the user has completed the pairing process
  • Check that phone numbers in Smokeball match the format used by the PBX
  • Ensure the contact exists in Smokeball with a phone number
  • Verify the correct region is selected in domain settings

Authentication fails:

  • Ensure popup blockers are disabled
  • Verify you're logging into the correct Smokeball region
  • Check that your Smokeball account has API access enabled
  • Try unpairing and pairing again