Skip to content

Getting Started

Before implementing endpoints, tokens, and payload handling, it helps to understand the integration as one connected lifecycle.

Telsmart integrations are not a one-time credential setup. They are an ongoing contract between Telsmart, your backend, and each activated user account. A backend service under your control is required to implement activation callbacks, token lifecycle management, and webhook ingestion:

  1. The user starts activation from your app.
  2. The user gives consent in a Telsmart user portal called MyTelsmart.
  3. Telsmart calls your backend server-to-server to activate the integration and deliver you tokens.
  4. Your backend keeps the integration alive by managing rotating OAuth tokens.
  5. Telsmart pushes real-time call data to your webhook.
  6. Your backend uses REST APIs for management/configuration use cases.

If you model your integration around this lifecycle, most implementation decisions become straightforward.

The Integration Story

Think of Telsmart backend as a platform that does two things in parallel once a user is connected:

  • It authorizes your backend to act on behalf of that user account (activation + OAuth lifecycle).
  • It streams operational call data to your system through events (webhooks).

This means your backend should be designed as a stateful integration service, not as a static API client with manually pasted credentials.

flowchart LR
    A[User clicks Connect in your app] --> B[Redirect to MyTelSmart activation page]
    B --> C[User logs in and grants consent]
    C --> F[Integration active]
    F --> G[Webhook events: calls and summaries]
    F --> H[REST API usage: configuration and data management]
    F --> I[Programmatic token refresh with rotated refresh tokens to access Telsmart APIs]
    I --> F
    F --> J[Deactivation flow ends lifecycle]

Activation Lifecycle

Activation is marketplace-style and user-initiated.

  • Your UI starts the process by redirecting to MyTelsmart.
  • Consent happens in MyTelsmart.
  • Telsmart completes activation by performing a mandatory server-to-server callback to your Activation URL. Your integration is not considered active until your backend validates this request and persists the issued tokens.

At activation time, your backend is expected to:

  • validate the activation request,
  • persist the received tokens securely,
  • associate them with the correct tenant/user context,
  • and store integration status as active.

This is the key architectural point: activation is an ongoing integration lifecycle entry point, not a static credential handoff.

Token Lifecycle

OAuth here should be treated as an automated token maintenance process.

  • Access tokens are short-lived.
  • Refresh tokens are single-use and rotated on each refresh.
  • Your backend must refresh tokens programmatically and persist newly issued refresh tokens each time.
  • Integration remains active until a deactivation flow explicitly ends it.

Because of this lifecycle behaviour, the integration cannot be implemented as a simple fixed authentication configuration. It requires active token lifecycle management and persistent integration state handling in your backend.

Real-time Events Model

Telsmart is primarily push-based for operational call data. Webhook event ingestion is the core integration mechanism, while REST APIs play a supporting role.

  • You provide a webhook endpoint.
  • Telsmart sends real-time events (call state changes and related updates).
  • Your backend processes events and updates your product state/UI accordingly.

Important expectation: call summaries and transcriptions are currently delivered via events only.

REST-based retrieval of summaries is planned, but not yet available.

Where REST APIs Fit

REST APIs are still important, but their role is different from webhooks.

Use REST mainly for:

  • configuration,
  • data management,
  • resources such as phonebooks, contacts, and related entities.

REST is not the primary real-time channel for call progress or summary delivery. REST APIs should not be used to model real-time call behaviour. Real-time state is delivered exclusively via webhook events.

Typical Responsibilities on Your Side

In practice, you usually need to implement:

  • activation/deactivation endpoints,
  • secure token storage and rotation logic,
  • integration state management per user/tenant,
  • webhook ingestion, validation, idempotent processing, and retry-safe handling,
  • REST-based management workflows where applicable.

Frequently Asked Questions

“Which authentication type is this?”

It is OAuth-based, but with lifecycle obligations (activation callback + rotating refresh-token management). It is not just a one-click OAuth button.

“Can I configure OAuth once and forget it?”

No. You must continuously refresh tokens and persist rotated refresh tokens.

“Can I pull call summaries from REST?”

Not currently. Call Summaries are delivered via events today; REST retrieval is planned.

“Can I start and manipulate a call from REST?”

Not currently. Call Control API is in development.

Next, continue with detailed implementation docs: