Wazo's JavaScript Software Development Kit
Wazo JavaScript SDK makes it easy for you to build Programmable Conversation applications.
Use this dev kit in any JS application to leverage communication possibilities.
Supported Features
Wazo's Javascript SDK allows you to use these features :
- Voice :
Voice
- Video :
Video
- Chat :
Chat
- Fax :
Fax
- Log :
Log
- Users status :
Status
- Users configurations :
Config
- Directories, Logs :
Misc
Table of contents
Install
Install / Add Voice
Video
Chat
Fax
Status
Config
Misc
You may install the Wazo JavaScript Software Development Kit to your project one of the following ways:
npm install @wazo/sdk
yarn add @wazo/sdk
Content Delivery Networks Voice
Video
Chat
Fax
Status
Config
Misc
Alternatively, you may load the Wazo SDK from a CDN. Use one of the following Content Delivery Networks:
UNPKG
<script src="https://unpkg.com/@wazo/sdk/dist/wazo-sdk.js"></script>
jsDelivr
<script src="https://cdn.jsdelivr.net/npm/@wazo/sdk"></script>
Simple API
Importing the Simple API
import Wazo from '@wazo/sdk/lib/simple';
<script src="https://unpkg.com/@wazo/sdk/dist/wazo-sdk.js"></script>
or
<script src="https://cdn.jsdelivr.net/npm/@wazo/sdk"></script>
Authentication with the simple API
Initializing
Wazo.Auth.init(clientId, tokenExpiration, minSubscriptionType, authorizationName);
clientId
: string (optional)
- An identifier of your application that will be used to refresh users token
tokenExpiration
: number (optional, default 3600 seconds)
- Duration before token expiration (in seconds)
minSubscriptionType
: number (optional)
- Defines the minimum user subscription type that allows access to your application.
authorizationName
: string (optional)
- Defines the name of the authorization the user should have to ba able to login.
Setting the engine host
Wazo.Auth.setHost(host);
host
: string
- URL to your host (include port if needed).
Customizing all the fetch
options
Wazo.Auth.fetchOptions({
referrer: '',
});
options
: Object
- Options passed to all the
fetch
requests of the SDK.
Authenticating an user
const session = await Wazo.Auth.logIn(username, password);
-
username
: string
-
password
: string
Returns as Wazo.domain.Session
. This object contains, among other information, the user's token.
Note: you need to set clientId
in your WazoAPIClient in order to get a refresh token in the returned Session
.
Validating a token
const session = await Wazo.Auth.validateToken(token, refreshToken);
token
: string
- User's token to validate (eg: makes sure the token is valid and not expired).
refreshToken
: string (optional)
- User's refresh token, used to generate a new token if expired.
Returns as Wazo.domain.Session
.
Setting a callback when a new token is refreshed
When the user's token is about to expire, Wazo's SDK triggers a callback so you can update it in your application.
Like updating the new token in your localstorage / cookies.
Note: you need to set clientId
in your WazoAPIClient in order to refresh tokens.
Wazo.Auth.setOnRefreshToken(token => { });
callback
: Function(token: string)
- A function that is triggered when the user's token will soon expire.
Loggin out
Destroys user's token and refreshToken.
await Wazo.Auth.logout();
Conference
Joining a room
Wazo.Room.connect(options);
options
: Objectextension
: string
The room extension (number) you want to joinaudio
: boolean|Object
A boolean, if you want to send the user audio or not; or an Object, if you want to specify the audio input, etc...
See getUserMedia arguments for more information.video
: boolean|Object
A boolean, if you want to send the user video or not; or an Object, if you want to specify the audio input, etc...
See getUserMedia arguments for more information.extra
: Object
A map of values that will be added to the information of the current participant.
Returns a Wazo.Room
instance.
Sending a chat message in the room
room.sendChat(content);
content
: string
The chat message content you want to send to all participants in the room.
Sending a custom message to all participants
room.sendSignal(content);
content
: string
The message content you want to send to all participants in the room.
Sharing the user screen
room.startScreenSharing(constraints);
Stopping the screen share
room.stopScreenSharing();
Disabling the camera
room.turnCameraOff();
Enabling the camera
room.turnCameraOn();
Disabling the microphone
room.mute();
Enabling the microphone
room.unmute();
Accessing room participants
room.participants;
participants
: An array of Wazo.LocalParticipant
and Wazo.RemoteParticipant
.
Disconnect from the room
Wazo.room.disconnect();
Conference events
room.on(room.ON_CHAT, (message) => {});
Triggered when receiving a chat message.
room.on(room.ON_MESSAGE, (message) => {});
Triggered when receiving a custom message.
room.on(room.ON_JOINED, (participant) => {});
Triggered when joining the room.
participant
: Wazo.LocalParticipant
.
room.on(room.CONFERENCE_USER_PARTICIPANT_JOINED, (participant) => {});
Triggered when a participant joins the room.
participant
: Wazo.RemoteParticipant
.
room.on(room.CONFERENCE_USER_PARTICIPANT_LEFT, (participant) => {});
Triggered when a participant leaves the room.
participant
: Wazo.RemoteParticipant
.
room.on(room.ON_SCREEN_SHARE_ENDED, () => {});
Triggered when screensharing is stopped.
participant
: Wazo.RemoteParticipant
.
room.on(room.ON_TALKING, (channel, participant) => {});
Triggered when a participant is talking, or stops talking.
channel
: Object containing information about the event.participant
: Wazo.RemoteParticipant
or Wazo.LocalParticipant
.
The participant instance, your can access the participant.isTalking
attribute to know the status.
Ad hoc Conference features Voice
Video
Merging sessions in one conference
Use this method to merge multiple calls in a new ad hoc conference.
const adHocConference = Wazo.Phone.startConference(host: CallSession, otherCalls: CallSession[]): Promise<AdHocAPIConference>;
Add a call to a conference
Use this method to add a single call to an existing conference room.
adHocConference.addParticipant(participant: CallSession);
Remove a call from a conference
Use this method to remove a participant from a conference.
adHocConference.removeParticipant(callSession: CallSession);
Terminating a conference
Use this method to remove a single participant from a conference.
adHocConference.hangup();
Accessing the current WebRtc phone
You can access the current webRtcPhone instance via Wazo.Phone.phone
.
Domains
You can access all Wazo's domain objects in Wazo.domain.*
, like Wazo.domain.Session
;
Participant
Wazo.LocalParticipant
and Wazo.RemoteParticipant
shares the same properties :
-
uuid
: string
The participant uuid.
-
name
: string
The participant name, retrieved from the sip configuration.
-
isTalking
: boolean
Indicates if the participant is currently talking.
-
streams
: Array of Wazo.Stream
List all streams that the participant is sending.
-
videoStreams
: Array of Wazo.Stream
List all video streams that the participant is sending.
-
audioMuted
: boolean
Indicates if the participant has muted his microphone.
-
videoMuted
: boolean
Indicates if the participant has muted his camera.
-
screensharing
: boolean
Indicates if the participant is currently sharing his screen.
-
extra
: Object
extra information related to a participant.
Participant events
participant.on(participant.ON_UPDATED, () => {});
Triggered when the participant is updated.
participant.on(participant.ON_START_TALKING, () => {});
Triggered when the participant is talking.
participant.on(participant.ON_STOP_TALKING, () => {});
Triggered when the participant stops talking.
participant.on(participant.ON_DISCONNECT, () => {});
Triggered when the participant leaves the room.
participant.on(participant.ON_STREAM_SUBSCRIBED, (stream) => {});
Triggered when the participant sends a stream.
stream
: Wazo.Stream
A Wazo stream that is sent by the participant.
participant.on(participant.ON_STREAM_UNSUBSCRIBED, (stream) => {});
Triggered when the participant stops sending a stream.
stream
: Wazo.Stream
A Wazo stream that is no longer sent by the participant.
participant.on(participant.ON_AUDIO_MUTED, () => {});
Triggered when the participant has disabled his microphone.
participant.on(participant.ON_AUDIO_UNMUTED, () => {});
Triggered when the participant has enabled his microphone.
participant.on(participant.ON_VIDEO_MUTED, () => {});
Triggered when the participant has disabled his camera.
participant.on(participant.ON_VIDEO_UNMUTED, () => {});
Triggered when the participant has enabled his camera.
participant.on(participant.ON_SCREENSHARING, () => {});
Triggered when the participant is sharing his screen.
participant.on(participant.ON_STOP_SCREENSHARING, () => {});
Triggered when the participant stop sharing his screen.
Stream
Wazo.Stream
helps attaching or detaching streams to html elements:
stream.attach(htmlEmelent)
Attaches a stream to an existing htmlElement or creates and returns a new one.
htmlElement
: htmlElement (optional).
Returns a htmlElement
(audio or video) attached to the stream.
stream.detach(htmlEmelent)
Detaches a stream from an existing htmlElement.
htmlElement
: htmlElement.
Advanced API
Libraries
Require / Import Voice
Video
Chat
Fax
Status
Config
Misc
Depending on your preference, you may require or add the Wazo SDK to your own client application one of the following ways using:
API Client Library
const { WazoApiClient } = require('@wazo/sdk');
import { WazoApiClient } from '@wazo/sdk';
Depending on your environment you can import:
@wazo/sdk/esm
: compatible with (most) browsers only.@wazo/sdk/lib
: runnable on node
env.
WebRTC Library
import { WazoWebRTCClient } from '@wazo/sdk';
WebSocket Library
import { WazoWebSocketClient } from '@wazo/sdk';
Authentication
Initialization Voice
Video
Chat
Fax
Status
Config
Misc
When using API Client
const client = new WazoApiClient({
server: 'stack.dev.wazo.io',
agent: null,
clientId: null,
isMobile: false,
});
When using WebRTC
const session = await client.auth.logIn({ ... });
Log In Voice
Video
Chat
Fax
Status
Config
Misc
client.auth.logIn({
expiration,
username,
password,
backend,
mobile,
}).then({
metadata: {
username,
uuid_tenant_uuid,
xivo_user_uuid,
groups,
xivo_uuid,
tenants: [{ uuid }],
auth_id
},
acl,
utc_expires_at,
xivo_uuid,
issued_at,
utc_issued_at,
auth_id,
expires_at,
xivo_user_uuid
});
const { refreshToken, ...result } = await client.auth.login();
Note: you need to set clientId
in your WazoAPIClient in order to get a refresh token.
Set token (and refresh token) Voice
Video
Chat
Fax
Status
Config
Misc
client.setToken(token);
client.setRefreshToken(refreshToken);
client.setRefreshTokenExpiration(tokenExpirationInSeconds);
Note: you need to set clientId
in your WazoAPIClient in order to get a refresh token.
Add an event when the token is refreshed Voice
Video
Chat
Fax
Status
Config
Misc
client.setOnRefreshToken((newToken, newSession) => {
});
Note: you need to set clientId
in your WazoAPIClient in order to refresh token.
Log Out Voice
Video
Chat
Fax
Status
Config
Misc
client.auth.logOut(token).then();
await client.auth.logOut(token);
Check token Voice
Video
Chat
Fax
Status
Config
Misc
client.auth.checkToken(token).then(valid);
// or
const valid = await client.auth.checkToken(token);
Other auth methods Config
client.auth.listTenants();
client.auth.createTenant(name);
client.auth.deleteTenant(uuid);
client.auth.createUser(username, password, firstname, lastname);
client.auth.addUserEmail(userUuid, email, main);
client.auth.addUserPolicy(userUuid, policyUuid);
client.auth.deleteUser();
client.auth.listUsers();
client.auth.listGroups();
client.auth.createPolicy(name, description, acl);
client.auth.listPolicies();
Sending logs to fluentd via a http endpoint
Logger Log
import Wazo from '@wazo/sdk/lib/simple';
Wazo.IssueReporter.enable();
Wazo.IssueReporter.configureRemoteClient({
host: 'localhost', // fluentd http host
port: 9880, // fluentd http port
tag: 'name of your application,
level: 'trace', // Min log level to be sent
extra: {
// Extra info sent for every logs
user_uuid: '...',
},
});
Using the logger :
// Log with for category, this will send a `category` attribute in every logs for this logger.
const logger = Wazo.IssueReporter.loggerFor('my_category');
logger(logger.TRACE, 'my log');
// or simply
Wazo.IssueReporter.log(Wazo.IssueReporter.INFO, 'my log');
Interact with the engine
Applicationd Voice
Video
Chat
Fax
Status
Config
Use Applicationd to construct your own communication features.
client.application.calls(applicationUuid);
client.application.hangupCall(applicationUuid, callId);
client.application.answerCall(applicationUuid, callId, context, exten, autoanswer);
client.application.listNodes(applicationUuid);
client.application.listCallsNodes(applicationUuid, nodeUuid);
client.application.removeCallNodes(applicationUuid, nodeUuid, callId);
client.application.addCallNodes(applicationUuid, nodeUuid, callId);
client.application.playCall(applicationUuid, callId, language, uri);
Calld Voice
Video
Chat
Fax
Status
Use Calld to directly control interactions.
(Please note, ctidNg endpoint is deprecated but continue to work with old version. Please update your code.)
client.calld.getConferenceParticipantsAsUser(conferenceId);
client.calld.answerSwitchboardQueuedCall(switchboardUuid, callId);
client.calld.answerSwitchboardHeldCall(switchboardUuid, callId);
client.calld.cancelCall(callId);
client.calld.deleteVoicemail(voicemailId);
client.calld.fetchSwitchboardHeldCalls(switchboardUuid);
client.calld.fetchSwitchboardQueuedCalls(switchboardUuid);
client.calld.getConferenceParticipantsAsUser(conferenceId);
client.calld.getPresence(contactUuid);
client.calld.getStatus(lineUuid);
client.calld.holdSwitchboardCall(switchboardUuid, callId);
client.calld.listCalls();
client.calld.listMessages(participantUuid, limit);
client.calld.listVoicemails();
client.calld.makeCall(extension, fromMobile, lineId, allLines);
client.calld.sendFax(extension, fax, callerId);
client.calld.sendMessage(alias, msg, toUserId);
client.calld.relocateCall(callId, destination, lineId);
client.calld.updatePresence(presence);
Confd Config
Use Confd to interact with configurations.
client.confd.listUsers();
client.confd.getUser(userUuid);
client.confd.getUserLineSip(userUuid, lineId);
client.confd.listApplications();
Dird Misc
Use Dird to interact with directories.
client.dird.search(context, term);
client.dird.listPersonalContacts();
client.dird.addContact(newContact);
client.dird.editContact(contact);
client.dird.deleteContact(contactUuid);
client.dird.listFavorites(context);
client.dird.markAsFavorite(source, sourceId);
client.dird.removeFavorite(source, sourceId);
Agentd Misc
Use Agentd to handle agent states
Legacy (all versions)
client.agentd.getAgent(agentNumber);
client.agentd.login(agentNumber, context, extension);
client.agentd.logout(agentNumber);
client.agentd.pause(agentNumber);
client.agentd.resume(agentNumber);
Log in with line ID only (engine version > 20.11 -- recommended)
client.agentd.loginWithLineId(lineId);
No-args methods (engine version >= 20.17 -- recommended)
client.agentd.getStatus();
client.agentd.staticLogout();
client.agentd.staticPause();
client.agentd.staticResume();
callLogd Voice
Misc
Use callLogd to interact with call logs.
client.callLogd.search(search, limit);
client.callLogd.listCallLogs(offset, limit);
client.callLogd.listCallLogsFromDate(from, number);
Chatd Chat
Status
Use chatd to send and retrieve chat messages and user statuses.
client.chatd.getContactStatusInfo(contactUuid: UUID);
client.chatd.getState(contactUuid: UUID);
client.chatd.getLineState(contactUuid: UUID);
client.chatd.getMultipleLineState(contactUuids: ?Array<UUID>);
client.chatd.getUserRooms();
client.chatd.updateState(contactUuid: UUID, state: string);
client.chatd.updateStatus(contactUuid: UUID, state: string, status: string);
client.chatd.createRoom(name: string, users: Array<ChatUser>);
client.chatd.getRoomMessages(roomUuid: string);
client.chatd.sendRoomMessage(roomUuid: string, message: ChatMessage);
client.chatd.getMessages(options: GetMessagesOptions);
Calling an API endpoint without WazoApiClient Voice
Video
Chat
Fax
Status
Config
Misc
Use this generic method to request endpoints directly.
const requester = new ApiRequester({
server: 'stack.dev.wazo.io',
refreshTokenCallback: () => {},
clientId: 'my-id',
agent: null,
token: null,
});
const results = await requester.call('dird/0.1/personal');
WebRTCClient
This sample decribes the very first steps to place a call using WebRTC.
import { WazoWebRTCClient } from '@wazo/sdk';
const session = await client.auth.logIn({ ... });
const client = new WazoWebRTCClient({
displayName: 'From WEB',
host: 'stack.dev.wazo.io',
media: {
audio: boolean,
video: boolean | document.getElementById('video'),
localVideo: boolean | document.getElementById('video'),
}
}, session);
client.on('invite', (sipSession: SipSession, hasVideo: boolean, shouldAutoAnswer: boolean) => {
this.currentSipSession = sipSession;
});
await client.waitForRegister();
client.call('1234');
WebRTCClient Configuration
const config = {
displayName: '',
host: '',
port: '',
media: {
audio: boolean,
video: boolean | document.getElementById('video'),
localVideo: boolean | document.getElementById('video'),
},
iceCheckingTimeout: 1000,
log: {},
audioOutputDeviceId: null,
userAgentString: null,
heartbeatDelay: 1000,
heartbeatTimeout: 5000,
maxHeartbeats: 4,
authorizationUser: '',
password: '',
uri: '',
}
const uaConfigOverrides = {
peerConnectionOptions: {
iceServers = [
{urls: "stun:stun.example.com:443"},
{urls: "turn:turn.example.com:443", username: "login", credential: "secret" },
...
]
}
}
const client = new WazoWebRTCClient(config, session, uaConfigOverrides);
Basic client features Voice
Video
Chat
Calling a number
Use this method to dial a number.
client.call(number: string);
Be notified to a phone call
Use this method to be notified of an incoming call.
client.on('invite', (sipSession: SipSession) => {
this.currentSipSession = sipSession;
});
Answering a call
Use this method to pick up an incoming call.
client.answer(sipSession: SipSession);
Hangup a call
Use this method to hangup a call (the call must have been already picked up)
client.hangup(sipSession: SipSession);
Rejecting a call
Use this method to deny an incoming call (Must not have been picked up already)
client.reject(sipSession: SipSession);
Muting a call
Use this method to mute yourself in a running call.
client.mute(sipSession: SipSession);
Unmuting a call
Use this method to unmute yourself in a running call.
client.unmute(sipSession: SipSession);
Holding a call
Use this method to put a running call on hold.
client.hold(sipSession: SipSession);
Unholding a call
Use this method to resume a running call.
client.unhold(sipSession: SipSession);
Make a blind transfer
Use this method to transfer a call to another target, without introduction
client.transfer(sipSession: SipSession, target: string);
Make an attended transfer
Use this method to transfer a call to another target, but first introduce the caller to the transfer target. The transfer may be cancelled (hangup the transfer target) or completed (hangup the transfer initiator).
transfer = client.atxfer(sipSession: SipSession);
transfer.init(target: string)
targetSession = transfer.newSession
transfer.complete()
transfer.cancel()
Sending a DTMF tone
Use this method to send the dual-tone multi-frequency from the phone keypad.
client.sendDTMF(sipSession: SipSession, tone: string);
Sending a message
client.message(destination: string, message: string);
Set the audio output volume
Stores a value between 0 and 1, which can be used to on your audio element
phone.changeAudioOutputVolume(volume: number);
Set the audio ring volume
Stores a value between 0 and 1, which can be used to on your audio element
phone.changeAudioRingVolume(volume: number);
Closing the RTC connection
Use this method to put an end to an RTC connection.
client.close();
WebRTCPhone
Higher level of abstraction to use the WebRtcClient
.
import { WazoWebRTCClient, WebRTCPhone } from '@wazo/sdk';
const webRtcClient = new WazoWebRTCClient({});
const phone = new WebRTCPhone(
webRtcClient: WazoWebRTCClient,
audioDeviceOutput: string,
allowVideo: boolean,
audioDeviceRing,
);
Basic phone features Voice
Video
Chat
Calling a number
Use this method to dial a number.
const callSession = await phone.makeCall(
number: string,
line:
enableVideo: boolean
);
Hangup a call
Use this method to stop a call
phone.hangup(
callSession: CallSession,
);
Accepting a call
Use this method to accept (answer) an incoming call
phone.accept(
callSession: CallSession,
cameraEnabled?: boolean
);
Rejecting a call
Use this method to reject an incoming call
phone.reject(
callSession: CallSession
);
Holding a call
Use this method to put a running call on hold.
phone.hold(
callSession: CallSession,
withEvent: boolean = true
);
Resuming a call
Use this method to resume a running call.
phone.resume(callSession: CallSession);
Please note that phone.resume()
is the preferred method
phone.unhold(callSession: CallSession);
Muting a call
Use this method to mute yourself in a running call.
phone.mute(
callSession: CallSession,
withEvent: boolean = true
);
Unmuting a call
Use this method to unmute yourself in a running call.
phone.unmute(callSession: CallSession);
Muting camera in a call
Use this method to mute your camera in a running call.
phone.turnCameraOff(callSession: CallSession);
Unmuting camera in a call
Use this method to unmute your camera in a running call.
phone.turnCameraOn(callSession: CallSession);
Sending DTMF
Use this method to unmute yourself in a running call.
phone.sendKey(callSession: CallSession, tone: string);
Transferring a call
Blind transfer
Use this method to transfer a call directly to another extension, without introduction
phone.transfer(
callSession: CallSession,
target: string
);
Attended transfer
Use this method to transfer a call to another extension by allowing to speak with the other participant first and validate the transfer after that.
You have to run makeCall
first on the target to be able to confirm the transfer with this method.
phone.indirectTransfer(
callSession: CallSession,
target: string
);
Start screen sharing
const screenShareStream: MediaStream = await phone.startScreenSharing({
audio: true,
video: true,
});
Stop screen sharing
phone.stopScreenSharing();
Conference phone features Voice
Video
Chat
Starting a conference
Use this method to start an ad-hoc conference.
phone.startConference(participants: CallSession[]);
Adding a participant to the conference
phone.addToConference(participant: CallSession);
Holding a conference
phone.holdConference(participants: CallSession[]);
Resuming a conference
phone.resumeConference(participants: CallSession[]);
Muting a conference
phone.muteConference(participants: CallSession[]);
Unmuting a conference
phone.unmuteConference(participants: CallSession[]);
Removing participants from a conference
phone.removeFromConference(participants: CallSession[]);
Stopping a conference
phone.hangupConference(participants: CallSession[]);
Advanced phone features Voice
Video
Chat
Registering the phone
Sends a SIP REGISTER
payload
phone.register();
Check if the phone is registered
phone.isRegistered();
Un-registering the phone
Sends a SIP UNREGISTER
payload
phone.unregister();
Updating audio output device
phone.changeAudioDevice(someDevice: string);
Updating audio ring device
phone.changeRingDevice(someDevice: string);
Updating audio input device
phone.changeAudioInputDevice(someDevice: string);
Updating video input device
phone.changeVideoInputDevice(someDevice: string);
Checking if it has an active call
phone.hasAnActiveCall(): boolean;
Retrieve the number of active calls
phone.callCount(): number;
Sending a SIP message
Sends a SIP MESSAGE in a session.
Use phone.currentSipSession
to retrieve the current sipSession
.
phone.sendMessage(
sipSession: SipSession = null, The sip session where to send to message
body: string,
);
Closing the phone
Disconnect the SIP webSocket transport.
phone.stop();
Starting heartbeat
Sends a SIP OPTIONS
every X seconds, Y times and timeout after Z seconds.
See webrtcClient's heartbeatDelay
, heartbeatTimeout
, maxHeartbeats
, configuration.
phone.startHeartbeat();
Stopping heatbeat
phone.stopHeartbeat();
Wazo WebSocket
You can use the Wazo WebSocket to listen for real time events (eg: receiving a chat message, a presential update ...)
Web Socket features Voice
Video
Chat
Fax
Status
Opening the socket
import { WebSocketClient } from '@wazo/sdk';
const ws = new WebSocketClient({
host: '',
token: '',
events: [''],
version: 2,
}, {
});
ws.connect();
Listening for event
import { USERS_SERVICES_DND_UPDATED, AUTH_SESSION_EXPIRE_SOON } from '@wazo/sdk/lib/websocket-client';
ws.on('eventName', (data: mixed) => {
});
ws.on(USERS_SERVICES_DND_UPDATED, ({ enabled }) => {
});
ws.on(AUTH_SESSION_EXPIRE_SOON, (data) => {
});
Updating the user token
You can update a new token to avoid being disconnected when the old one will expire.
ws.updateToken(newToken: string);
Closing the socket
ws.close();