Overview

Nextiva’s four SDKs share a unified architecture that governs their backend communication, as well as their data and media stream management. This article outlines the core architecture components and details how our SDKs interact with the system.

Communication layers

The SDKs communicate with the backend using two main channels:

HTTP Requests

These are used for commands like:

• Dialing a number
• Muting/unmuting a call
• Retrieving a list of users

WebSocket connections

Once an HTTP command is issued, the server opens one or more WebSocket connections for real-time communication. There are two types of WebSockets:

• Events socket (real time communication)
  • Handles system events like incoming calls, status changes, and offer notifications
• Analytics socket
  • Sends supervisory data like users, queues, campaigns, outbound lists and workitem statistics.

Voice handling

Bi-directional WebSocket communication is used for signaling between the browser and FreeSwitch using the mod_verto protocol. Once a successful connection is established and a call is handled, the audio flows over RTP.

SDK-server interaction

When a user interacts with the SDK by placing a call or logging in, that interaction is translated to a server command. In turn, the server sends corresponding events back to the client. In the React SDK, we expose this data via React hooks, allowing you to easily render updates. You can register to an event service that will give updates coming from the server.

SDK to NEXT flow

When a user logs in via the SDK:

1. Credentials are sent to the Provider Service, which authenticates the user. The Provider Service returns a token and payload with instructions on where to send future requests. The token returned in this authentication call is needed on all subsequent requests and is handled automatically by the SDK by adding this request to the HTTP header.
2. Requests are routed via the nextiva.io domain (currently thrio.io). Regional domains are currently being established for the US, Canada, Europe, and India.
3. This distributed architecture includes multiple clusters designed with automatic failover and redundancy. The SDK simplifies connectivity by automatically establishing and managing the necessary connections, including WebSocket and HTTP connections, as well as the voice connection to FreeSWITCH:

• Services

The NCXPaaS SDK provides a suite of services, each encapsulating a specific set of functionalities to handle communication with the backend. These services manage real-time request/response interactions using WebSockets and HTTP APIs.

• REACT hooks

The SDK exposes a collection of React hooks designed to simplify data access. These hooks automatically fetch relevant data, maintain its state, and update in real-time as events are received from the server.

• Notification events

The SDK supports real-time event handling through WebSocket messages. Events are surfaced to the client via hook updates or a dedicated event handler service. For example, events may include agent status changes (Available, Busy, On Break) or new interactions (calls, emails, chats, etc.). On mobile platforms, the SDK leverages Firebase Cloud Messaging (FCM) to receive backend notifications.

• Communication

The SDK manages WebRTC-based communication between the client device and the FreeSwitch cluster. It automatically handles connection and reconnection when a user is configured for WebRTC, ensuring reliable voice and media sessions.

• Schema types

The SDK uses Schema Types to define the structure of domain objects like User, Queue, Campaign, and others. These schema definitions serve as the foundation for all CRUD operations (Create, Read, Update, Delete) exposed by the SDK, maintaining consistency across integrations.