Skip to main content

Integrations

The One Voice integrates with the rest of The One Stack and supports embedding in external applications via an SSO widget.

The One PSA​

The PSA integration is the deepest integration Voice has with any other product.

What Flows​

DataDirectionDetails
Caller lookupVoice ← PSAWhen an inbound call arrives, Voice queries PSA for matching contacts by phone number
Open ticketsVoice ← PSAThe softphone screen pop shows open PSA tickets for the caller's company
Account statusVoice ← PSAVIP, active/inactive status shown in the screen pop
Call historyVoice → PSACalls appear in the PSA contact's activity timeline
Call-to-ticketVoice → PSAAgents can create a PSA ticket directly from the softphone (one click)
Billing line itemsVoice → PSAWhen billing integration mode is Integrated, Voice sends pending charges to PSA for unified invoicing
AI sentiment feedVoice → PSAPost-call sentiment scores and action items are pushed to the PSA data feed endpoint

Setup​

  1. In the Voice dashboard, go to Settings → Integrations → PSA
  2. Enter the PSA API URL and PSA Integration Key
  3. Toggle Enable Screen Pop to show caller context in the softphone
  4. Toggle Enable Timeline to write call history back to PSA contact records
  5. Save

The PSA integration key is a service-to-service key (X-Integration-Key header) — it is separate from your user login.

The One CRM​

The CRM integration provides caller lookup and contact matching for organizations using CRM as their primary contact database.

What Flows​

DataDirectionDetails
Caller lookupVoice ← CRMInbound caller matched to CRM contacts by phone number
Contact nameVoice ← CRMMatched contact name shown in softphone and call log
Call logVoice → CRMCalls appear in CRM contact activity timeline

Setup​

  1. Go to Settings → Integrations → CRM
  2. Enter the CRM API URL and CRM Integration Key
  3. Save

The One Books​

The Books integration handles billing event emission — Voice reports usage events (minutes, SMS, numbers) to Books for consolidated billing.

What Flows​

Voice sends the following events to Books:

  • voice.minutes — per-call usage in seconds
  • voice.sms — per-message SMS usage
  • voice.number — monthly phone number rental events
  • voice.fax — per-fax usage

These events are fire-and-forget (non-blocking). If Books is temporarily unavailable, events are queued and retried.

Setup​

The Books integration is configured by the platform admin or MSP admin — end tenants do not configure this directly. The relevant env vars are BOOKS_API_URL and VOICE_BOOKS_API_KEY on the Voice API.

Embed Widget (PSA / CHMS / AMS)​

The Voice embed widget drops the full phone system into any web application with a <script> tag.

How SSO Bridge Works​

  1. The host app calls POST /api/sso/token with its integration API key
  2. The Voice API returns a signed 5-minute JWT
  3. The embed widget loads and exchanges the JWT via POST /api/sso/exchange
  4. Voice auto-creates a Voice user linked to the host app's user account
  5. The widget renders the full Voice dashboard inside an iframe — no separate login required

Embedding​

<script
  src="https://app.theonevoice.app/embed.js"
  data-api-key="YOUR_VOICE_API_KEY"
  data-container="#voice-widget"
></script>
<div id="voice-widget"></div>

Embed Widget Options​

AttributeDescription
data-api-keyYour Voice integration API key
data-containerCSS selector for the container element
data-modesoftphone (phone panel only) or full (full dashboard)
data-themelight or dark
data-extensionPre-select a specific extension by ID

Click-to-Call​

The embed widget listens for a custom DOM event. To trigger a call from the host application:

document.dispatchEvent(new CustomEvent('softphone-dial', {
  detail: { number: '+12125551234' }
}));

SAML / OIDC SSO​

The One Voice supports enterprise SSO via SAML 2.0 and OIDC.

Setup​

  1. Go to Settings → SSO Providers
  2. Click Add Provider
  3. Choose SAML 2.0 or OIDC
  4. For SAML: Enter the Entity ID, SSO URL, and X.509 certificate from your IdP
  5. For OIDC: Enter the Client ID, Client Secret, and Discovery URL (the .well-known/openid-configuration endpoint)
  6. Set Domain Restriction — only email addresses from your domain can use this provider
  7. Toggle JIT Provisioning — automatically creates Voice users on first SSO login
  8. Save

Your IdP needs:

  • SAML ACS URL: https://api.theonevoice.app/api/auth/sso/saml/callback
  • SAML Entity ID: https://theonevoice.app
  • OIDC Redirect URI: https://api.theonevoice.app/api/auth/sso/oidc/callback

Microsoft 365 / Azure AD​

Voice supports M365 login via the Hub IAM SSO bridge. If your Hub account is linked to M365, your Voice login inherits M365 authentication automatically — no separate SSO provider configuration needed.

Developer API​

For custom integrations, Voice exposes a full REST API with API key authentication.

  1. Go to Developer → API Keys
  2. Click Create API Key
  3. Give it a name and select permission scopes
  4. Copy the key — it is shown only once

API documentation: docs.theonestack.com/voice/api-reference

Outbound webhooks (calls, SMS, fax events) can be configured in Developer → Webhooks.

Troubleshooting Integrations​

IssueCheck
Screen pop not showing PSA dataVerify PSA Integration Key is set and PSA API URL is correct; check that caller's phone number matches a PSA contact
Books events not appearingConfirm BOOKS_API_URL and VOICE_BOOKS_API_KEY env vars are set on the Voice API
SSO embed not loadingVerify the API key is valid and the data-container selector matches an existing DOM element
SAML login failsCheck that the clock on your IdP server is synchronized (SAML assertions have a 5-minute clock skew tolerance)