The Call Widget is a Click-to-Call style JavaScript widget which uses the SignalWire SDK and the SignalWire C2C service to allow you to embed calls in your website.
npm install @niravcodes/call-widgetThe Call Widget is a Click-to-Call style JavaScript widget which uses the SignalWire SDK and the SignalWire
C2C service to allow you to embed calls in your website.
> 🌟 New V3 Beta Available!
> We've released a new version (V3) of the Call Widget with a completely revamped API, better UI, and support for incoming calls.
> Skip to V3 Documentation
Import the widget from the CDN:
``html`
or install the widget using npm:
`bash`
npm install @niravcodes/call-widget
`html
token="
callDetails='{"destination":"/private/demo-1","supportsVideo":false,"supportsAudio":true}'
collectUserDetails="false"
survey='{"title":"Please take this survey", "description":"We would love to hear your thoughts. Would you like to take a survey?","href":"https://www.google.com"}'
userVariables='{"user_type":"guest"}'
>
`
| Parameter | Type | Required | Default | Description |
| -------------------- | ------- | -------- | --------- | ----------------------------------------------------------- |
| [buttonId] | string | Yes | - | ID for Button that triggers call |
| [token] | string | Yes | - | Authentication token (c2c or embeds) |
| [callDetails] | object | Yes | - | Call configuration JSON |
| [collectUserDetails] | boolean | No | true | Show user details form boolean |
| [survey] | object | No | not shown | Post-call survey config JSON |
| [userVariables] | object | No | {} | Custom call variables JSON (arbitrary JSON key:value pairs) |
[buttonId]: #buttonid
[token]: #token
[callDetails]: #calldetails
[collectUserDetails]: #collectuserdetails
[survey]: #survey
[userVariables]: #uservariables
The buttonId attribute is used to specify the ID of the HTML button element that will trigger the call.
If the button is not found, the widget will wait for the button to be created. (The button doesn't have to exist in the DOM at the time of widget initialization.)
You can use the class .demo-button-disabled to disable the button while the widget is loading. The widget will remove that particular
class once it loads.
`html`
Authentication token for SignalWire services (either the c2c token from the dashboard, or the embed token).
Using C2C token is getting recommended for most cases. You can get the C2C token from the SignalWire Space dashboard.
You can get the embed token using the Embeds Token API.
You can also use any token received from the Call Fabric authentication, assuming it has the necessary permissions to the address.
The callDetails object is used to configure the call including destination and media support:
- destination: string - Call destinationsupportsVideo
- : boolean - Enable/disable videosupportsAudio
- : boolean - Enable/disable audio
Strict JSON format is required for this attribute.
Whether to show a form collecting user details before starting call.
The survey object is used to configure the post-call survey:
- title: string - Survey modal title (optional, defaults to "Would you like to take a survey?")description
- : string - Survey description text (optional, defaults to "We would love to hear your thoughts. Would you like to take a survey? It only takes 2 minutes.")href
- : string - URL to survey (required)
Don't set this attribute if you don't want a survey to be shown.
Strict JSON format is required for this attribute.
Custom variables to attach to the call session. Can be any JSON key:value pair. The following will be overridden by the widget, however:
`
callOriginHref - the URL of the page where the widget is hosted
userName - the name of the user (if they input it in the form)
userEmail - the email of the user (if they input it in the form)
userPhone - the phone number of the user (if they input it in the form)
Strict JSON format is required for this attribute.
This event is triggered when the call is about to start.
`javascript`
const widget = document.querySelector("c2c-widget");
widget.addEventListener("beforecall", () => {
console.log("beforecall");
});
A completely revamped version of the Call Widget with a modern API, enhanced UI, and support for incoming calls. V3 offers a more streamlined integration experience and additional features not available in V2.
Key improvements over V2:
- Simpler, more intuitive HTML attribute-based configuration
- Built-in support for incoming calls
- Enhanced UI with multiple window modes
- Better debugging options
- More flexible audio codec configuration
`bash`
npm install @niravcodes/call-widget@next
`html`
`html
token="your_signalwire_token"
destination="/private/demo"
support-audio="true"
support-video="true"
>
`
| Attribute | Required | Default | Description |
| ---------------- | -------- | ------------------ | -------------------------------------------------- |
| token | Yes | - | SignalWire authentication token |
| destination | Yes | - | Call destination path |
| button-id | Yes | - | ID of the button that triggers the call |
| support-audio | No | false | Enable audio support |
| support-video | No | false | Enable video support |
| window-mode | No | "video+transcript" | UI mode for the call window |
| log-level | No | "error" | Logging verbosity level |
| host | No | - | SignalWire server host |
| receive-calls | No | false | Enable incoming call reception |
| auto-answer | No | false | Automatically answer incoming calls without prompt |
| audio-codec | No | - | Comma-separated list of preferred audio codecs |
| user-variables | No | - | Custom variables passed as JSON string |
| debug-ws-traffic | No | false | Enable WebSocket traffic debugging |
#### token
Your SignalWire authentication token. This is required for establishing connections.
Example:
`html`
#### destination
The destination path for the call. Usually in the format "/private/room-name".
Example:
`html`
#### window-mode
Controls the layout and features of the call window. Available options:
- video+transcript: Video call with transcriptvideo
- : Video-only interfaceaudio+transcript
- : Audio call with transcript
Example:
`html`
#### log-level
Sets the logging verbosity. Available options:
- debug: Most verbose, includes all logsinfo
- : General information and important eventswarn
- : Warnings and non-critical issueserror
- : Only error messages (default)
Example:
`html`
#### user-variables
Custom variables passed as a JSON string. All values must be strings.
Example:
`html`
>
#### audio-codec
Comma-separated list of preferred audio codecs.
Example:
`html`
`html
token="your_token"
destination="/private/audio-room"
support-audio="true"
support-video="false"
window-mode="audio+transcript"
>
`
`html
token="your_token"
destination="/private/video-room"
support-audio="true"
support-video="true"
window-mode="video+transcript"
log-level="info"
>
`
`html
token="your_token"
destination="/private/agent-room"
support-audio="true"
support-video="true"
receive-calls="true"
auto-answer="false"
window-mode="video+transcript"
user-variables='{"agentId": "agent123", "department": "support"}'
>
`
1. Token Security: Never hardcode your SignalWire token in the HTML. Instead, fetch it dynamically from your server.
However, you're free to use click2call tokens (c2c_...) statically in HTML.
2. Button Placement: The trigger button can be styled and positioned anywhere in your layout. Just ensure the button-id matches.
3. window-mode vs support-audio and support-video:
- window-mode controls the layout UI of the widget. This is purely cosmetic.support-audio
- and support-video controls the features of the widget. This decides if webcam and/or microphone is used.
V3 introduces robust support for incoming calls, making it suitable for call center and customer service applications.
To enable incoming calls, set the receive-calls attribute to "true". You can also configure automatic answer behavior using auto-answer.
`html`
token="your_token"
destination="/private/agent-room"
receive-calls="true"
auto-answer="false"
window-mode="video+transcript"
>
When receive-calls is enabled:
1. The widget listens for incoming calls to the specified destination
2. When a call arrives:
- If auto-answer="true": The call is automatically answeredauto-answer="false"
- If : A notification appears allowing the user to accept or declinewindow-mode
3. The call window opens in the specified once the call is accepted
1. User Experience:
- Use auto-answer="false" for agent interfaces where call screening is neededauto-answer="true"
- Use for automated services or IVR systemsvideo+transcript
2. Window Mode: For agent interfaces, mode provides the most comprehensive call handling experiencesupport-audio
3. Audio/Video Support: Configure and support-video based on your use case:`
html``
support-audio="true"
support-video="true"
window-mode="video+transcript"
>