twilio-client-redux
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.16 • Public • Published

    Twilio Client Redux

    Purpose

    This package is intended to be used with twilio-client.js and to make integrating its event emitters with redux very straightforward. We recommend using it along side Redux Toolkit for several reasons and all code examples are shown with RTK implementations.

    The general implementation of this library is currently very opinionated, but should work for every use case - if you have any specific requests, please open an issue or PR and we'd be happy to include it. Our goal is to track twilio-client releases and upgrade as necessary.

    Note: As of right now, Twilio does not export types that are easily consumable in their frontend libraries, but we do our best to give you an accurate representation of the serializable device and connection when appropriate. This is mostly just for logging purposes as you can't call methods on the serialized Device or Connection objects.

    Installation

    Using npm:

    npm i twilio-client-redux
    

    Using yarn:

    yarn add twilio-client-redux
    

    Usage

    Add the middleware

    At a high level, the implementation looks like this:

    1. Add the middleware
    2. Create a device instance with your capability token by dispatching setup(token, options)
    3. dispatch actions to make calls, control the device, etc etc.
    4. Respond to events in relevant reducers to handle Device and/or Connection events
    5. Have a phone party!

    The middleware accepts the following options:

    export interface MiddlewareOptions {
      storeAudioDevices?: boolean; // default = true. store the payload of setInputDevice/setOutputDevice to localStorage. will automatically try to use the values when setting up a future device.
      connectOnIncoming?: boolean; // default = true. automatically accept incoming connections
      prefix?: string; // default = @tcr. currently unimplemented and may be implemented in the future
    }

    Example implementation:

    // store.ts
     
    import { configureStore, Action, getDefaultMiddleware } from '@reduxjs/toolkit';
    import TwilioClientRedux from 'twilio-client-redux';
     
    import rootReducer, { RootState } from './rootReducer';
     
    const store = configureStore({
      reducer: rootReducer,
      middleware: [...getDefaultMiddleware(), TwilioClientRedux()],
    });
     
    export type AppDispatch = typeof store.dispatch;
     
    export default store;

    Initialize a device

    // MyPhoneApp.ts
    import React, { useEffect } from "react";
    import { useDispatch, useSelector } from "react-redux";
    import { setup } from "twilio-client-redux";
     
    export const MyPhoneApp = () => {
     
    const dispatch = useDispatch();
     
    useEffect(() => {
      // You could fetch a token here, or pass it in as a prop, or whatever makes sense for your app
        dispatch(setup(token, { debug: true }));
    }, [token])
    });
     
    return (<PhoneUI />);
     
    };

    Device setup options:

    Accepts the standard twilio-client Device options:

    declare interface DeviceConfigOptions {
      allowIncomingWhileBusy?: boolean;
      audioConstraints?: MediaTrackConstraints | boolean;
      closeProtection?: boolean | string;
      codecPreferences?: Codec[];
      debug?: boolean;
      disableAudioContextSounds?: boolean;
      dscp?: boolean;
      enableIceRestart?: boolean;
      enableRingingState?: boolean;
      fakeLocalDTMF?: boolean;
      forceAggressiveIceNomination?: boolean;
      maxAverageBitrate?: number;
      region?: string;
      rtcConfiguration?: RTCConfiguration;
      sounds?: Partial<Record<SoundName, string>>;
      warnings?: boolean;
    }

    Device actions:

    Note: All devices actions take an optional parameter of deviceId. By default, this is set to 'default'. This allows you to manage multiple devices if your implementation requires that.

    setup(); // initialize a device.
    destroy(); // destroy the device instance and disconnect all connections. you will need to call setup again to create a new device.
    setOutputDevice(); // if you passed in storeAudioDevices: true to `setup`, this will store in localStorage. it will attempt to be reused when the device initialized in the future
    setInputDevice(); // sets the input device and behaves the same as setOutputDevice
    testOutputDevice(); // can be used to play a chime on the currently set output device

    Managing connections

    We provide every method that is available to twilio-client.js as exported actions. All methods take an optional deviceId parameter.

    makeCall();
    hangupCall();
    sendDigit(); // sends a digit to the active connection
     
    setMute(); // mute the current connection on the device
    toggleMute(); // toggles the mute state
    getMuteStatus(); // returns `{ muted: value }`
     
    getStatus(); // returns the status of the active connection
     
    acceptCall();
    rejectCall();
    ignoreCall();

    Responding to middleware-generated actions in a reducer

    By default, the middleware creates actions for every twilio-client event listener. Depending on your redux setup, you can append .type to the end of the action you're looking for to get it's type value (ex: onReady.type === @tcr::DEVICE_READY).

    In a non-createSlice implementation, that might look like:

    // phoneReducer.js
    // ... reducer code
    switch (action.type) {
      case onReady.type:
      // Do things when the device is ready
    }

    Included action types that are created after initializing a Device

    onReady;
    onCancel;
    onConnect;
    onError;
    onDisconnect;
    onIncoming;
    onOffline;

    Example slice responding to common use cases:

    // phoneSlice.ts
     
    import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';
    import {
      onReady,
      onConnect,
      onDisconnect,
      getMuteStatus,
    } from 'twilio-client-redux';
    import { RootState } from 'src/store/rootReducer';
    import { apiRequest } from 'src/utils';
     
    // in this case, we make an API request to our server to initiate a call. being that
    // the default value in the middleware is to automatically accept incoming connections
    // our call will be bridged immediately. your implementation will vary.
    export const makeCall = createAsyncThunk(
      'phone/makeCall',
      async (phone: string) => {
        const {
          data: { data },
        } = await apiRequest.post<Call>(`agent/calls`, { phone });
        return data;
      }
    );
     
    const initialState = {
      call: {},
      muted: false,
      status: 'idle',
    };
     
    const slice = createSlice({
      name: 'phone',
      initialState,
      reducers: {},
      extraReducers: builder => {
        builder.addCase(onReady, (state, action) => {
          // Note that action is type safe here and will return a serialized `Device`
          state.status = 'idle';
        });
        builder.addCase(onConnect, (state, action) => {
          // Note that action is type safe here and will return a serialized `Connection`
          state.status = 'active';
        });
        builder.addCase(onDisconnect, (state, action) => {
          // Note that action is type safe here and will return a serialized `Device`
          return initialState;
        });
        builder.addCase(makeCall.pending, (state, action) => {
          // set state to ringing when we initiate the API request to start the call
          state.status = 'ringing';
        });
        builder.addCase(makeCall.fulfilled, (state, action) => {
          // Note that action is type safe here and will return a action.payload will be the type of Call from our API
          state.status = 'active';
          state.call = action.payload;
        });
        builder.addCase(getMuteStatus, (state, action) => {
          state.muted = action.payload.muted;
        });
      },
    });
     
    export default slice.reducer;
     
    export const selectIsMuted = (state: RootState) => state.phone.muted;

    Keywords

    Install

    npm i twilio-client-redux

    DownloadsWeekly Downloads

    1

    Version

    1.0.16

    License

    MIT

    Unpacked Size

    2.53 MB

    Total Files

    25

    Last publish

    Collaborators

    • msutkowski
    • themindoverall