@tmsoft/webphone

SIP softphone component for Vue 3 and Web Components.

Installation

npm install @tmsoft/webphone

Usage

Vue 3

<script setup lang="ts">
import { WebPhone } from '@tmsoft/webphone'
</script>

<template>
  <WebPhone host="pbx.example.com" extension="1001" password="your-password" />
</template>

Web Component

<script src="https://unpkg.com/@tmsoft/webphone/dist/webphone.component.js"></script>

<web-phone host="pbx.example.com" extension="1001" password="your-password"></web-phone>

Props

| Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | host | string | No* | — | SIP server hostname. WebSocket URL: wss://<host>:8089/asterisk/ws | | wsUrl | string | No* | — | Custom WebSocket URL. Takes precedence over host | | extension | string | Yes | — | SIP extension | | password | string | Yes | — | SIP password | | mode | 'webcall' \| 'call' \| 'video' | No | 'call' | Operating mode | | logo | string | No | — | Logo URL for webcall mode | | to | string | No | — | Auto-dial number for webcall mode | | contacts | WebPhoneContact[] | No | [] | Contact list | | initialKeypadVisible | boolean | No | true | Initial keypad visibility | | enablePictureInPicture | boolean | No | true | Enables Document Picture-in-Picture | | maskNumber | boolean | No | false | Masks the displayed call number after its first 3 digits (for example, 315*******) | | earlyMedia | boolean | No | false | Enables audio from provisional SIP responses with SDP for outbound, non-forking calls | | onAnswer | (video: boolean) => void \| Promise<void> | No | — | Custom handler for answer action (incoming call) | | onHangup | () => void \| Promise<void> | No | — | Called when hangup is requested; SIP hangup is always sent by the component | | onReject | () => void \| Promise<void> | No | — | Custom handler for reject action (incoming call) |

* Either host or wsUrl must be provided.

Modes

| Mode | Description | | --- | --- | | call | Standard softphone with keypad and call history | | video | Softphone with video support | | webcall | Click-to-call widget. Requires to and logo |

Types

interface WebPhoneContact {
  name: string
  number: string
  type?: 'tool' | 'extension' | 'contact' | 'voicemail'
}

Action handlers

If onAnswer or onReject are provided, the component calls those props instead of executing the corresponding internal SIP action. onHangup is called in addition to the internal SIP hangup, which the component always initiates.

Events

| Event | Description | | --- | --- | | back | Back button pressed | | call-context | Emits channelId, SIP Call-ID, direction and remote number when a SIP session is created | | call-state | Emits dialing, ringing, connected, ended or failed with the call context | | media-ready | Emits separate localStream and remoteStream objects when both audio tracks are ready |

sipCallId is the SIP dialog identifier. It is not the Asterisk Uniqueid or Linkedid. Consumers may read the emitted streams but must not stop or mutate their tracks; the WebPhone owns their lifecycle.

Releasing a new version

Publishing is automated: CI reacts to what you push, so a release is a version bump plus a push. Never run npm publish by hand.

# 1. Land the changes on master first — CI publishes what the tag points at.
git checkout master && git pull

# 2. Bump. Creates the release commit AND the tag in one step.
npm version patch     # or minor / major

# 3. Push the commit together with its tag.
git push --follow-tags

Step 2 needs no extra flags because .npmrc already pins the release conventions: git-tag-version=true creates the tag, tag-version-prefix=v names it vX.Y.Z, and message="chore(release): v%s" writes the commit subject. Bump minor or major for anything past a patch, but keep in mind consumers pinned to ^3.0.x still pick a new minor up automatically.

What CI does with the tag

| Workflow | Triggered by | Publishes to | | --- | --- | --- | | ci.yml | push to master / develop, tags v*, PRs | — builds and uploads the dist artifact | | publish-npm.yml | successful CI on master or a v* tag | npm as @tmsoft/webphone | | publish-github.yml | successful CI on a v* tag only | GitHub Packages, rescoped to the repo owner |

Both publish jobs reuse the dist artifact CI already built and fall back to yarn install && yarn build:lib if the download fails.

Pushing to master without a version bump also fires the npm publish job, and it fails on the already-taken version. Harmless, but it is why a red publish run right after a merge is usually not a real problem.

Consuming the new version

Downstream projects use Yarn 4:

yarn up @tmsoft/webphone            # latest — also rewrites the range in package.json
yarn up @tmsoft/webphone@^3.0.19    # a specific version

Yarn refuses packages younger than its npmMinimalAgeGate (24 h by default), which a release published minutes ago always trips. Consumers that need to pick a version up immediately set npmMinimalAgeGate: 0 in their .yarnrc.yml — as this repo and calloperator-frontend both do.

Verify the published bundle actually carries the change instead of trusting the version number, since the publish jobs reuse a prebuilt artifact:

node -p "require('./node_modules/@tmsoft/webphone/package.json').version"

License

MIT