ES6 Module JavaScript

Welcome


@@@@@@@        @@@         @@@@@@       @@@       @@@@@@@         @@@@@@    @@@@@@@        @@@@@@@
 @@@@@@@      @@@@@      @@@@@@@       @@@@@@      @@@@@@@      @@@@@@@      @@@@@@@      @@@@@@@
  @@@@@@@    @@@@@@@@   @@@@@@@       @@@@@@@@       @@@@@@@   @@@@@@@        @@@@@@@    @@@@@@
   @@@@@@@ @@@@@@@@@@@ @@@@@@@       @@@@@@@@@@       @@@@@@@ @@@@@@@          @@@@@@@ @@@@@@@
    @@@@@@@@@@@@@@@@@@@@@@@@@      @@@@@@@@@@@@@       @@@@@@@@@@@@@            @@@@@@@@@@@@@
      @@@@@@@@@@ @@@@@@@@@@@      @@@@@@@  @@@@@@       @@@@@@@@@@                @@@@@@@@@@
       @@@@@@@@   @@@@@@@@       @@@@@@@    @@@@@@@      @@@@@@@@                  @@@@@@@@
        @@@@@       @@@@@       @@@@@@@      @@@@@@@       @@@@@                    @@@@@
         @@@         @@@       @@@@@@@        @@@@@@@       @@@                      @@@
{ "title": "WAVV Docs", "lastUpdated": "2024-05-15T21:51:17.515Z" }

Welcome to WAVV's developer documentation!

Ready to supercharge your app?

Learn about our communication widgets:

Make sure to review our REST API.

We've also written some helpful guides.

And outlined our data structures.

Dialer

Latest version: 4.0.0

Quick Start

To get started, follow these simple steps:


1. Include

Step 1:

npm install @wavv/dialer
<script src="https://app.wavv.com/js/dialer-4.0.0.js"></script>

There are two ways to include the widget:

You'll also need to add <div id="wavv-dialer"></div> to your HTML.

The div determines where the dialer will appear in your app.


2. Initialize

Step 2:

import { init } from '@wavv/dialer';

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });
const { init } = window.WavvDialer;

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });

Initialize the widget with a token.

For more information, see the guide on Tokens.


3. Listen

Step 3:

import { addCallStartedListener } from '@wavv/dialer';

const listener = addCallStartedListener(({ number }) => {
    console.log(`Calling ${number}...`);
});
const { addCallStartedListener } = window.WavvDialer;

const listener = addCallStartedListener(({ number }) => {
    console.log(`Calling ${number}...`);
});

Add listeners for the events you care about.

(This step is optional.)


4. Start

Step 4:

import { callPhone } from '@wavv/dialer';

callPhone({
    number: '9143504210',
    contact: {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
});
const { callPhone } = window.WavvDialer;

callPhone({
    number: '9143504210',
    contact: {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
});

Fire it up with Start Campaign or Call Phone.

And you're done. Congratulations!

Functions

Init

import { init } from '@wavv/dialer';

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });
const { init } = window.WavvDialer;

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });

Initializes the widget and authenticates the user.

Parameters

Name Type Required Description
token string yes Token
groupId string no Group ID
subgroupId string no Subgroup ID
server string no Subdomain override



Set Theme

import { setTheme } from '@wavv/dialer';

setTheme({ theme: 'LIGHT', primaryColor: '#BF6350' });
const { setTheme } = window.WavvDialer;

setTheme({ theme: 'LIGHT', primaryColor: '#BF6350' });

Changes the appearance of WAVV to suit your fancy.

Parameters

Name Type Required Description
theme string yes LIGHT or DARK
primaryColor string no Hex color code



Open Settings

import { openSettings } from '@wavv/dialer';

openSettings();
const { openSettings } = window.WavvDialer;

openSettings();

Opens the settings modal.



Start Campaign

import { startCampaign } from '@wavv/dialer';

const contacts = [
    {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
        address: '1344 Queens Boulevard',
        city: 'Long Island',
    },
];

startCampaign({ contacts });
const { startCampaign } = window.WavvDialer;

const contacts = [
    {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
        address: '1344 Queens Boulevard',
        city: 'Long Island',
    },
];

startCampaign({ contacts });

Loads contact data and launches the dialer. If no contacts are provided the campaign launcher modal will open, allowing the user to select an existing campagin to resume.

Parameters

Name Type Required Description
contacts Contact[] no Contacts for the campaign
mini boolean no Use the mini dialer



End Campaign

import { endCampaign } from '@wavv/dialer';

endCampaign();
const { endCampaign } = window.WavvDialer;

endCampaign();

Ends the current campaign and optionally closes the dialer.

Parameters

Name Type Required Description
close boolean no Also close the dialer after ending the campaign



Call Phone

import { callPhone } from '@wavv/dialer';

callPhone({
    number: '9143504210',
    contact: {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
});
const { callPhone } = window.WavvDialer;

callPhone({
    number: '9143504210',
    contact: {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
});

Loads a single number and launches the dialer (click-to-call).

Parameters

Name Type Required Description
number string yes Phone number to call
contact Contact yes Associated contact
mini boolean no Use the mini dialer



Add Phone

import { addPhone } from '@wavv/dialer';

addPhone({
    number: '9143504210',
    contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
});
const { addPhone } = window.WavvDialer;

addPhone({
    number: '9143504210',
    contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
});

Adds a number to a contact in the campaign.

Parameters

Name Type Required Description
number string yes Phone number to add
contactId string yes Associated contact ID



Remove Phone

import { removePhone } from '@wavv/dialer';

removePhone({
    number: '9143504210',
    hangup: true,
});
const { removePhone } = window.WavvDialer;

removePhone({
    number: '9143504210',
    hangup: true,
});

Removes a number from the campaign.

Parameters

Name Type Required Description
number string yes Phone number to remove
hangup boolean no Hangup call to number (if any)



Remove Contact

import { removeContact } from '@wavv/dialer';

removeContact({
    contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
    hangup: true,
    resume: true,
});
const { removeContact } = window.WavvDialer;

removeContact({
    contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
    hangup: true,
    resume: true,
});

Removes a contact from the campaign.

Parameters

Name Type Required Description
contactId string yes ID of the contact to remove
hangup boolean no Hangup calls to contact (if any)
resume boolean no Resume the campaign



Continue Campaign

import { continueCampaign } from '@wavv/dialer';

continueCampaign({
    resume: true,
});
const { continueCampaign } = window.WavvDialer;

continueCampaign({
    resume: true,
});

Allows the campaign to continue (enables the resume button).

Used in conjunction with Waiting For Continue.

Parameters

Name Type Required Description
resume boolean no Resume the campaign



Add DNC Number

import { addDncNumber } from '@wavv/dialer';

addDncNumber({
    number: '9143504210',
    addedBy: 'Kramer',
});
const { addDncNumber } = window.WavvDialer;

addDncNumber({
    number: '9143504210',
    addedBy: 'Kramer',
});

Adds a number to the DNC list.

Parameters

Name Type Required Description
number string yes Phone number to add
addedBy string no Who added the number



Remove DNC Number

import { removeDncNumber } from '@wavv/dialer';

removeDncNumber({
    number: '9143504210',
});
const { removeDncNumber } = window.WavvDialer;

removeDncNumber({
    number: '9143504210',
});

Removes a number from the DNC list.

Parameters

Name Type Required Description
number string yes Phone number to remove



List Voicemails

import { listVoicemails } from '@wavv/dialer';

listVoicemails().then((vms) => {
    vms.forEach(({ id, name, seconds }) => {
        console.log(id, name, seconds);
    });
});
const { listVoicemails } = window.WavvDialer;

listVoicemails().then((vms) => {
    vms.forEach(({ id, name, seconds }) => {
        console.log(id, name, seconds);
    });
});

Lists the user's voicemail recordings.

Used in conjunction with Drop Voicemail.



Drop Voicemail

import { dropVoicemail } from '@wavv/dialer';

dropVoicemail({ id: '2b954111-3c2b-402c-93d6-f8b1dfa470db' });
const { dropVoicemail } = window.WavvDialer;

dropVoicemail({ id: '2b954111-3c2b-402c-93d6-f8b1dfa470db' });

Drops a voicemail on the current call.

Logically equivalent to pressing the "Drop VM" button.

Parameters

Name Type Required Description
id string yes Voicemail ID



Record Call

import { recordCall } from '@wavv/dialer';

recordCall();
const { recordCall } = window.WavvDialer;

recordCall();

Records the current call.

Logically equivalent to pressing the "Record" button.



Show Mini

import { showMini } from '@wavv/dialer';

showMini({ mini: true, minimized: true });
const { showMini } = window.WavvDialer;

showMini({ mini: true, minimized: true });

Toggles between the dial bar and the mini dialer.

Parameters

Name Type Required Description
mini boolean yes Display the mini dialer
minimized boolean no Minimize the dialer



Close

import { close } from '@wavv/dialer';

close();
const { close } = window.WavvDialer;

close();

Closes the dialer, ending any active campaign.


Listeners

Call Started

import { addCallStartedListener } from '@wavv/dialer';

const listener = addCallStartedListener(({ number }) => {
    console.log(`Calling ${number}...`);
});
const { addCallStartedListener } = window.WavvDialer;

const listener = addCallStartedListener(({ number }) => {
    console.log(`Calling ${number}...`);
});

Fired when a call starts dialing.

Properties

Name Type Description
number string Phone number
contactId string Associated contact ID



Call Answered

import { addCallAnsweredListener } from '@wavv/dialer';

const listener = addCallAnsweredListener(({ number }) => {
    console.log(`Call to ${number} answered...`);
});
const { addCallAnsweredListener } = window.WavvDialer;

const listener = addCallAnsweredListener(({ number }) => {
    console.log(`Call to ${number} answered...`);
});

Fired when a call is answered.

Properties

Name Type Description
number string Phone number
contactId string Associated contact ID
backgrounded boolean Call answered on a background line



Call Ended

import { addCallEndedListener } from '@wavv/dialer';

const listener = addCallEndedListener(({ number }) => {
    console.log(`Call to ${number} ended...`);
});
const { addCallEndedListener } = window.WavvDialer;

const listener = addCallEndedListener(({ number }) => {
    console.log(`Call to ${number} ended...`);
});

Fired when a call ends.

Properties

Name Type Description
number string Phone number
contactId string Associated contact ID
duration number Duration of the call in seconds
human boolean A human was detected on the call
answered boolean Call was answered
outcome string Call Outcome



Call Recorded

import { addCallRecordedListener } from '@wavv/dialer';

const listener = addCallRecordedListener(({ number }) => {
    console.log(`Call to ${number} recorded...`);
});
const { addCallRecordedListener } = window.WavvDialer;

const listener = addCallRecordedListener(({ number }) => {
    console.log(`Call to ${number} recorded...`);
});

Fired when a call has been recorded.

Properties

Name Type Description
number string Phone number
contactId string Associated contact ID
recordingId string Call recording ID
autoSaveRecordings boolean True if the call was recorded with the "Record All Calls" setting enabled



Lines Changed

import { addLinesChangedListener } from '@wavv/dialer';

const listener = addLinesChangedListener(({ lines }) => {
    const call = lines.find(({ focused }) => focused);
    if (call) {
        navigateToContact(call.contactId);
        highlightPhoneNumber(call.number);
    }
});
const { addLinesChangedListener } = window.WavvDialer;

const listener = addLinesChangedListener(({ lines }) => {
    const call = lines.find(({ focused }) => focused);
    if (call) {
        navigateToContact(call.contactId);
        highlightPhoneNumber(call.number);
    }
});

Fired when dialing lines change.

Properties

Name Type Description
lines array Current dialing lines
lines[].number string Phone number
lines[].contactId string Associated contact ID
lines[].focused boolean Number should have focus
lines[].skippedNumbers array Skipped numbers on the contact



Dialer Idle

import { addDialerIdleListener } from '@wavv/dialer';

const listener = addDialerIdleListener(({ idle }) => {
    console.log(`Dialer is now ${idle ? 'idle' : 'active'}...`);
});
const { addDialerIdleListener } = window.WavvDialer;

const listener = addDialerIdleListener(({ idle }) => {
    console.log(`Dialer is now ${idle ? 'idle' : 'active'}...`);
});

Fired when idle state changes.

The dialer becomes idle when there are no numbers left to dial. A timer will be displayed, showing how much time is left before the dialer will auto-disconnect. At this point, the user can end their session or load more numbers.

Properties

Name Type Description
idle boolean Dialer is currently idle



Waiting For Continue

import { addWaitingForContinueListener } from '@wavv/dialer';

const listener = addWaitingForContinueListener(
    ({ waiting, number }) => {
        if (waiting) promptForDisposition(number);
    }
);
const { addWaitingForContinueListener } = window.WavvDialer;

const listener = addWaitingForContinueListener(
    ({ waiting, number }) => {
        if (waiting) promptForDisposition(number);
    }
);

Fired when waiting state changes.

By default, the dialer will wait to continue after every answered call. The resume button will be disabled, allowing you to gather additional information from the user. When it's safe to proceed, call Continue Campaign.

Properties

Name Type Description
waiting boolean Dialer is currently waiting
number string Phone number
contactId string Associated contact ID



Campaign Ended

import { addCampaignEndedListener } from '@wavv/dialer';

const listener = addCampaignEndedListener(({ history }) => {
    console.log(`Campaign ended, made ${history.length} calls...`);
});
const { addCampaignEndedListener } = window.WavvDialer;

const listener = addCampaignEndedListener(({ history }) => {
    console.log(`Campaign ended, made ${history.length} calls...`);
});

Fired when a campaign ends.

Properties

Name Type Description
complete boolean All numbers were dialed
history array Call Ended objects from the campaign



Dialer Visible

import { addDialerVisibleListener } from '@wavv/dialer';

const listener = addDialerVisibleListener(({ visible }) => {
    console.log(`Dialer is now ${visible ? 'visible' : 'hidden'}...`);
});
const { addDialerVisibleListener } = window.WavvDialer;

const listener = addDialerVisibleListener(({ visible }) => {
    console.log(`Dialer is now ${visible ? 'visible' : 'hidden'}...`);
});

Fired when dialer visibility changes.

Properties

Name Type Description
visible boolean Dialer is currently visible



Overlay Visible

import { addOverlayVisibleListener } from '@wavv/dialer';

const listener = addOverlayVisibleListener(({ visible }) => {
    console.log(`Overlay is now ${visible ? 'visible' : 'hidden'}...`);
});
const { addOverlayVisibleListener } = window.WavvDialer;

const listener = addOverlayVisibleListener(({ visible }) => {
    console.log(`Overlay is now ${visible ? 'visible' : 'hidden'}...`);
});

Fired when overlay visibility changes.

Certain dialogs and modals display a full-screen overlay.

Properties

Name Type Description
visible boolean Overlay is currently visible



DNC Changed

import { addDncChangedListener } from '@wavv/dialer';

const listener = addDncChangedListener(({ lines }) => {
    const call = lines.filter(({ focused }) => focused)[0];
    if (call) {
        navigateToContact(call.contactId);
        highlightPhoneNumber(call.number);
    }
});
const { addDncChangedListener } = window.WavvDialer;

const listener = addDncChangedListener(({ lines }) => {
    const call = lines.filter(({ focused }) => focused)[0];
    if (call) {
        navigateToContact(call.contactId);
        highlightPhoneNumber(call.number);
    }
});

Fired when a number is added or removed from the DNC list.

Properties

Name Type Description
number string Phone number
removed boolean Number was removed
type string DNC Type



Upsell Click

import { addUpsellClickListener } from '@wavv/dialer';

const listener = addUpsellClickListener(() => {
    displayOpportunity();
});
const { addUpsellClickListener } = window.WavvDialer;

const listener = addUpsellClickListener(() => {
    displayOpportunity();
});

Fired when the user clicks an upsell link.

Only applicable if you've chosen to handle billing.



Manage Subscription

import { addManageSubscriptionListener } from '@wavv/dialer';

const listener = addManageSubscriptionListener(() => {
    displayBilling();
});
const { addManageSubscriptionListener } = window.WavvDialer;

const listener = addManageSubscriptionListener(() => {
    displayBilling();
});

Fired when the user wants to manage their subscription.

Only applicable if you've chosen to handle billing.


Changelog

v4.0.0


v3.0.0


v2.5.0


v2.4.0


v2.3.0


v2.1.0


v2.0.0


Messenger

Latest version: 3.0.1

Quick Start

To get started, follow these simple steps:


1. Include

Step 1:

npm install @wavv/messenger
<script src="https://app.wavv.com/js/messenger-3.0.1.js"></script>

There are two ways to include the widget:


2. Initialize

Step 2:

import { init } from '@wavv/messenger';

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });
const { init } = window.WavvMessenger;

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });

Initialize the widget with a token.

For more information, see the guide on Tokens.


3. Listen

Step 3:

import { addMessageSentListener } from '@wavv/messenger';

const listener = addMessageSentListener(({ number }) => {
    console.log(`Message sent by ${number}...`);
});
const { addMessageSentListener } = window.WavvMessenger;

const listener = addMessageSentListener(({ number }) => {
    console.log(`Message sent by ${number}...`);
});

Add listeners for the events you care about.

(This step is optional.)


4. Start

Step 4:

import { openMessenger } from '@wavv/messenger';

openMessenger();
const { openMessenger } = window.WavvMessenger;

openMessenger();

Fire it up with Open Messenger.

And you're done. Congratulations!

Functions

Init

import { init } from '@wavv/messenger';

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });
const { init } = window.WavvMessenger;

await init({ token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' });

Initializes the widget and authenticates the user.

Parameters

Name Type Required Description
token string yes Token
groupId string no Group ID
subgroupId string no Subgroup ID
server string no Subdomain override



Set Theme

import { setTheme } from '@wavv/messenger';

setTheme({ theme: 'LIGHT', primaryColor: '#BF6350' });
const { setTheme } = window.WavvMessenger;

setTheme({ theme: 'LIGHT', primaryColor: '#BF6350' });

Changes the appearance of WAVV to suit your fancy.

Parameters

Name Type Required Description
theme string yes LIGHT or DARK
primaryColor string no Hex color code



Open Settings

import { openSettings } from '@wavv/messenger';

openSettings();
const { openSettings } = window.WavvMessenger;

openSettings();

Opens the settings modal.



Open Messenger

import { openMessenger } from '@wavv/messenger';

openMessenger({});
const { openMessenger } = window.WavvMessenger;

openMessenger({});

Opens the Messenger.

Parameters

Name Type Required Description
dock boolean no Open in docked mode
minimized boolean no Start minimized (if docked)
contactView boolean no Show contact-centric view
contact Contact no Contact for contactView



Open Messenger Thread

import { openMessengerThread } from '@wavv/messenger';

openMessengerThread({
    number: '9143504210',
    dock: true,
    contact: {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
        address: '1344 Queens Boulevard',
        city: 'Long Island',
        avatarUrl:
            'https://wavv-public.s3.amazonaws.com/docs/summer/george.jpg',
        mergeFields: [
            { id: 'sqft', value: '4,000' },
            { id: 'neighborhood', value: 'Briarwood' },
        ],
    },
});
const { openMessengerThread } = window.WavvMessenger;

openMessengerThread({
    number: '9143504210',
    dock: true,
    contact: {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
        address: '1344 Queens Boulevard',
        city: 'Long Island',
        avatarUrl:
            'https://wavv-public.s3.amazonaws.com/docs/summer/george.jpg',
        mergeFields: [
            { id: 'sqft', value: '4,000' },
            { id: 'neighborhood', value: 'Briarwood' },
        ],
    },
});

Opens the Messenger to a specific thread.

Parameters

Name Type Required Description
number string yes Phone number of recipient
dock boolean no Open in docked mode
minimized boolean no Start minimized (if docked)
contact Contact no Contact for number



Start Blast

import { startBlast } from '@wavv/messenger';

const contacts = [
    {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
];

startBlast({ contacts });
const { startBlast } = window.WavvMessenger;

const contacts = [
    {
        contactId: '0c3322de-9cbe-4916-8404-8ed5c427bdfa',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
];

startBlast({ contacts });

Opens the Messenger and starts a blast message.

Parameters

Name Type Required Description
contacts Contact[] yes Contacts for the blast message



Set Merge Fields

import { setMergeFields } from '@wavv/messenger';

setMergeFields({
    fields: [
        { id: 'sqft', label: 'Square Feet' },
        { id: 'neighborhood', label: 'Neighborhood' },
    ],
});
const { setMergeFields } = window.WavvMessenger;

setMergeFields({
    fields: [
        { id: 'sqft', label: 'Square Feet' },
        { id: 'neighborhood', label: 'Neighborhood' },
    ],
});

Adds custom merge field options.

For more information, see the guide on Merge Fields.

Parameters

Name Type Required Description
fields array yes Custom merge fields
fields[].id string yes Merge field ID
fields[].label string yes Merge field label


Listeners

import { addContactSearchListener } from '@wavv/messenger';

const listener = addContactSearchListener(
    ({ search, contacts, callback }) => {
        // callback expects an array of contact objects
        if (search) {
            const terms = search.trim().split(/\s+/);
            const results = findContactsBySearchTerms(terms);
            callback(results);
        } else if (contacts) {
            const results = contacts.map((contact) => {
                const { id, numbers } = contact;
                // ID might be unknown, find by phone number(s) if necessary
                return id
                    ? findContactById(id)
                    : findContactByNumbers(numbers);
            });
            callback(results);
        }
    }
);
const { addContactSearchListener } = window.WavvMessenger;

const listener = addContactSearchListener(
    ({ search, contacts, callback }) => {
        // callback expects an array of contact objects
        if (search) {
            const terms = search.trim().split(/\s+/);
            const results = findContactsBySearchTerms(terms);
            callback(results);
        } else if (contacts) {
            const results = contacts.map((contact) => {
                const { id, numbers } = contact;
                // ID might be unknown, find by phone number(s) if necessary
                return id
                    ? findContactById(id)
                    : findContactByNumbers(numbers);
            });
            callback(results);
        }
    }
);

Fired when contact data is needed from your app.

Properties

Name Type Description
search string Free-form search by the user
contacts Contact[] Specific contacts to return
callback function Callback for passing results



import { addContactLinkListener } from '@wavv/messenger';

const listener = addContactLinkListener(({ contact, callback }) => {
    navigateToContact(contact.id)
        .then(() => {
            // contact found, close the WAVV modal
            callback({ closeModal: true });
        })
        .catch((error) => {
            // contact not found, display error in WAVV
            callback({ displayError: true });
        });
});
const { addContactLinkListener } = window.WavvMessenger;

const listener = addContactLinkListener(({ contact, callback }) => {
    navigateToContact(contact.id)
        .then(() => {
            // contact found, close the WAVV modal
            callback({ closeModal: true });
        })
        .catch((error) => {
            // contact not found, display error in WAVV
            callback({ displayError: true });
        });
});

Fired when your app should display a contact record.

I.e. the user has clicked a link and expects to be shown contact details.

Name Type Description
contact Contact Contact to display
callback function Callback for controlling behavior



Message Sent

import { addMessageSentListener } from '@wavv/messenger';

const listener = addMessageSentListener(({ number }) => {
    console.log(`Message sent by ${number}...`);
});
const { addMessageSentListener } = window.WavvMessenger;

const listener = addMessageSentListener(({ number }) => {
    console.log(`Message sent by ${number}...`);
});

Fired when a message is sent.

Properties

Name Type Description
id string Message ID
number string Receiving phone number
body string Body of the message
attachments array Attachment URLs
blastId string Associated blast (if applicable)



Message Received

import { addMessageReceivedListener } from '@wavv/messenger';

const listener = addMessageReceivedListener(({ number }) => {
    console.log(`Message received from ${number}...`);
});
const { addMessageReceivedListener } = window.WavvMessenger;

const listener = addMessageReceivedListener(({ number }) => {
    console.log(`Message received from ${number}...`);
});

Fired when a message is received.

Properties

Name Type Description
id string Message ID
number string Sending phone number
body string Body of the message
attachments array Attachment URLs



Unread Count

import { addUnreadCountListener } from '@wavv/messenger';

const listener = addUnreadCountListener(
    ({ unreadCount, numberCounts }) => {
        console.log(`Unread message counts...`);
        console.log(`Total: ${unreadCount}`);
        console.log(`George: ${numberCounts['9143504210'] || 0}`);
    }
);
const { addUnreadCountListener } = window.WavvMessenger;

const listener = addUnreadCountListener(
    ({ unreadCount, numberCounts }) => {
        console.log(`Unread message counts...`);
        console.log(`Total: ${unreadCount}`);
        console.log(`George: ${numberCounts['9143504210'] || 0}`);
    }
);

Fired when the number of unread messages changes.

Properties

Name Type Description
unreadCount number Total unread messages
numberCounts object Unread count by number



Overlay Visible

import { addOverlayVisibleListener } from '@wavv/messenger';

const listener = addOverlayVisibleListener(({ visible }) => {
    console.log(`Overlay is now ${visible ? 'visible' : 'hidden'}...`);
});
const { addOverlayVisibleListener } = window.WavvMessenger;

const listener = addOverlayVisibleListener(({ visible }) => {
    console.log(`Overlay is now ${visible ? 'visible' : 'hidden'}...`);
});

Fired when overlay visibility changes.

Certain dialogs and modals display a full-screen overlay.

Properties

Name Type Description
visible boolean Overlay is currently visible



Upsell Click

import { addUpsellClickListener } from '@wavv/messenger';

const listener = addUpsellClickListener(() => {
    displayOpportunity();
});
const { addUpsellClickListener } = window.WavvMessenger;

const listener = addUpsellClickListener(() => {
    displayOpportunity();
});

Fired when the user clicks an upsell link.

Only applicable if you've chosen to handle billing.



Manage Subscription

import { addManageSubscriptionListener } from '@wavv/messenger';

const listener = addManageSubscriptionListener(() => {
    displayBilling();
});
const { addManageSubscriptionListener } = window.WavvMessenger;

const listener = addManageSubscriptionListener(() => {
    displayBilling();
});

Fired when the user wants to manage their subscription.

Only applicable if you've chosen to handle billing.


Changelog

v3.0.0


v2.4.0


v2.3.1


v2.3.0


v2.1.0


v2.0.0


REST API

If you're new here, see the REST API guide.

Brand Registration

Retrieve the status of a user's SMS Brand Registration approval status.

Get Status

curl -L -X GET 'https://api.wavv.com/v2/users/:userId/brand-registration' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{ "status": "APPROVED" }
GET
api.wavv.com/v2/users/userId/brand-registration


Response Properties

Name Type Description
status Brand Status Status of brand registration

DNC List

List Numbers

curl -L -X GET 'https://api.wavv.com/v2/users/:userId/dnc' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "9630f787-03b9-4b89-ae96-dd432e9205ae",
        "number": "9143505590",
        "type": "MANUAL",
        "createdAt": "2024-05-15T18:54:18.918Z"
    }
]
GET
api.wavv.com/v2/users/userId/dnc

Recordings

List Recordings

curl -L -X GET 'https://api.wavv.com/v2/users/:userId/recordings' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "1cba95b7-8fdb-4dbe-b6f5-fc96730827b4",
        "contactId": "0c3322de-9cbe-4916-8404-8ed5c427bdfa",
        "date": "2024-05-15T05:26:29.162Z",
        "phone": "9143504210",
        "seconds": 86.125,
        "url": "https://file.wavv.com/recordings/d28f557e418974a51d008b7718efb8e9/9143504210.mp3"
    }
]
GET
api.wavv.com/v2/users/userId/recordings


Get Recording

curl -L -X GET 'https://api.wavv.com/v2/users/:userId/recordings/:recordingId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "id": "1cba95b7-8fdb-4dbe-b6f5-fc96730827b4",
    "contactId": "0c3322de-9cbe-4916-8404-8ed5c427bdfa",
    "date": "2024-05-15T05:26:29.162Z",
    "phone": "9143504210",
    "seconds": 86.125,
    "url": "https://file.wavv.com/recordings/d28f557e418974a51d008b7718efb8e9/9143504210.mp3"
}
GET
api.wavv.com/v2/users/userId/recordings/recordingId


Delete Recording

curl -L -X DELETE 'https://api.wavv.com/v2/users/:userId/recordings/:recordingId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{ "success": true }
DELETE
api.wavv.com/v2/users/userId/recordings/recordingId

Texting

List Numbers

curl -L -X GET 'https://api.wavv.com/v2/sms/numbers' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "number": "9143504210",
        "createdAt": "2024-05-15T21:32:50.984Z",
        "nickname": "App notification number",
        "callForwarding": "8444545111"
    }
]
GET
api.wavv.com/v2/sms/numbers



List phone numbers available (purchased) for A2P texting or on behalf of a user.


Query Parameters

Name Type Required Description
userId string no User ID to list numbers on behalf of


Search Numbers

curl -L -X POST 'https://api.wavv.com/v2/sms/numbers/search' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{ "areaCode": "914" }'

The above command returns JSON structured like this:

[
    {
        "areaCode": "914",
        "numbers": [
            { "number": "9143504210", "city": "Long Island", "state": "NY" }
        ]
    }
]
POST
api.wavv.com/v2/sms/numbers/search



Search for phone numbers available for purchase.


Body Parameters

Name Type Required Description
state string no State
areaCode string no Area code


Purchase Number

curl -L -X POST 'https://api.wavv.com/v2/sms/numbers/purchase' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{ "number": "9143504210" }'

The above command returns JSON structured like this:

{ "success": true }
POST
api.wavv.com/v2/sms/numbers/purchase



Purchase a phone number for A2P texting.


Body Parameters

Name Type Required Description
number string yes Number to purchase
nickname string no Display nickname
callForwarding string no Call forwarding number


Send Message

curl -L -X POST 'https://api.wavv.com/v2/sms/messages' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{ "to": "9143505590", "from": "9143504210", "body": "Hello, Newman." }'

The above command returns JSON structured like this:

{
    "success": true,
    "messageId": "e38a91c4-e664-4073-b98c-0aec0eed8cb7"
}
POST
api.wavv.com/v2/sms/messages



Send a text message from your app or on behalf of a user.


Body Parameters

Name Type Required Description
to string yes Destination phone number
from string no Sending phone number
userId string no User ID to send on behalf of
body string yes Body of the message
mediaUrl string|string[] no Media url(s) to include content as attachments
scheduledAt date no DateTime to schedule a message sent in the future


List Threads

curl -L -X GET 'https://api.wavv.com/v2/sms/threads' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "800b9e2b-c628-4290-b3f6-8f3562adeae6",
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "displayName": "Alice Answer",
        "displayNameLocked": false,
        "recipientCount": 1,
        "avatarUrl": "",
        "type": "NORMAL",
        "draft": false,
        "preview": "Hello, Newman.",
        "previewStatus": "SENT",
        "unreadCount": 0,
        "sortTime": "2024-05-15T05:19:32.532Z",
        "createdAt": "2024-02-02T02:01:50.153Z",
        "updatedAt": "2024-05-15T13:39:23.233Z",
        "deleted": false,
        "hidden": false
    }
]
GET
api.wavv.com/v2/sms/threads



List threads on behalf of a user.


Query Parameters

Name Type Required Description
userId string yes User ID to list threads on behalf of
search string no Query to search thread display name and message content
scheduled boolean no Boolean to query only threads with a scheduled messsage
contactId string no Query by contact ID


Delete Thread

curl -L -X DELETE 'https://api.wavv.com/v2/sms/threads/:threadId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "id": "056ef676-36c0-44b4-aed3-69e761f21b89",
    "userId": "37128401-4f29-43af-953d-8d800b386a57",
    "displayName": "Alice Answer",
    "displayNameLocked": false,
    "recipientCount": 1,
    "avatarUrl": "",
    "type": "NORMAL",
    "draft": false,
    "preview": "Hello, Newman.",
    "previewStatus": "SENT",
    "unreadCount": 0,
    "sortTime": "2024-05-15T14:21:44.803Z",
    "createdAt": "2024-04-07T08:07:38.825Z",
    "updatedAt": "2024-05-15T15:05:05.767Z",
    "deleted": false,
    "hidden": false
}
DELETE
api.wavv.com/v2/sms/threads/threadId



Deletes thread on behalf of a user.


Query Parameters

Name Type Required Description
userId string yes User ID to delete thread on behalf of


List Thread Messages

curl -L -X GET 'https://api.wavv.com/v2/sms/threads/:threadId/messages' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "9a48d6ab-a7a9-44dd-afbd-892503090596",
        "appId": "99d2e056-af4e-4a73-9361-04bd2d2e25bd",
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "type": "NORMAL",
        "draft": false,
        "status": "SENT",
        "body": "Hello, Newman.",
        "rawBody": "Hello, Newman.",
        "mergeFields": [],
        "mergeFailed": false,
        "unread": false,
        "scheduledAt": "2024-05-15T06:52:49.225Z",
        "sortTime": "2024-05-15T03:40:15.680Z",
        "createdAt": "2024-05-15T18:17:16.537Z",
        "updatedAt": "2024-05-15T04:14:38.062Z",
        "authorId": "37128401-4f29-43af-953d-8d800b386a57",
        "recipientId": null,
        "omitted": false,
        "hidden": false,
        "attachments": [],
        "deleted": false,
        "thread": {
            "id": "91eba559-81cb-450f-bf2a-80d56d40e83a",
            "userId": "37128401-4f29-43af-953d-8d800b386a57",
            "deleted": false,
            "draft": false,
            "type": "NORMAL",
            "hidden": false
        },
        "blastMessage": null,
        "blastMessages": []
    }
]
GET
api.wavv.com/v2/sms/threads/threadId/messages



List thread messages on behalf of a user.


Query Parameters

Name Type Required Description
userId string yes User ID to list threads on behalf of
before date no Query to filter threads before the given date



Delete Message

curl -L -X DELETE 'https://api.wavv.com/v2/sms/threads/:threadId/messages/:messageId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "id": "5d21aef8-bf64-4bc0-81d6-81f4eb9a360a",
    "appId": "db32333d-b410-4060-bf8d-0fb0891764fb",
    "userId": "37128401-4f29-43af-953d-8d800b386a57",
    "type": "NORMAL",
    "draft": false,
    "status": "SENT",
    "body": "Hello, Newman.",
    "rawBody": "Hello, Newman.",
    "mergeFields": [],
    "mergeFailed": false,
    "unread": false,
    "scheduledAt": "2024-05-15T06:28:51.744Z",
    "sortTime": "2024-05-15T07:36:15.004Z",
    "createdAt": "2024-05-15T15:39:56.250Z",
    "updatedAt": "2024-05-15T14:14:35.047Z",
    "authorId": "37128401-4f29-43af-953d-8d800b386a57",
    "recipientId": null,
    "omitted": false,
    "hidden": false,
    "attachments": [],
    "deleted": false,
    "thread": {
        "id": "5ff7d5ed-f6b4-454a-911d-6f22860334f5",
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "deleted": false,
        "draft": false,
        "type": "NORMAL",
        "hidden": false
    },
    "blastMessage": null,
    "blastMessages": []
}
DELETE
api.wavv.com/v2/sms/threads/threadId/messages/messageId



Deletes message on behalf of a user.


Query Parameters

Name Type Required Description
userId string yes User ID to delete message on behalf of

Tokens

Create Token

curl -L -X POST 'https://api.wavv.com/v2/token' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{ "userId": "37128401-4f29-43af-953d-8d800b386a57" }'

The above command returns JSON structured like this:

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "payload": { "userId": "37128401-4f29-43af-953d-8d800b386a57" }
}
POST
api.wavv.com/v2/token


Body Parameters

Name Type Required Description
userId string yes User ID to authenticate


Response Properties

Name Type Description
token string JWT for the user

Users

List Users

curl -L -X GET 'https://api.wavv.com/v2/users' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "37128401-4f29-43af-953d-8d800b386a57",
        "firstName": "George",
        "lastName": "Costanza",
        "phone": "9143504210",
        "email": "george@vandelayindustries.com",
        "address1": "1344 Queens Boulevard",
        "city": "Long Island",
        "state": "NY",
        "zip": "11101",
        "test": false,
        "subscriptions": { "single": true, "sms": true }
    }
]
GET
api.wavv.com/v2/users


Response Properties

Name Type Description
id string Unique ID
firstName string First name
lastName string Last name
email string Email address
phone string Phone number
address1 string Address
address2 string Address line 2
city string City
state string State
zip string Zip
test boolean Testing account
subscriptions object Subscriptions
subscriptions.single boolean Power Dialer Single Line
subscriptions.multi boolean Power Dialer Multiple Line
subscriptions.previewLine boolean Preview Line Dialer
subscriptions.c2c boolean Click to Call Dialer
subscriptions.smsBasic boolean SMS Basic
subscriptions.sms boolean SMS Pro


Get User

curl -L -X GET 'https://api.wavv.com/v2/users/:userId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "id": "37128401-4f29-43af-953d-8d800b386a57",
    "firstName": "George",
    "lastName": "Costanza",
    "phone": "9143504210",
    "email": "george@vandelayindustries.com",
    "address1": "1344 Queens Boulevard",
    "city": "Long Island",
    "state": "NY",
    "zip": "11101",
    "test": false,
    "subscriptions": { "single": true, "sms": true },
    "signedTos": { "DIALER": true },
    "numbers": {
        "personal": ["9143505590"],
        "purchased": ["9143504210"]
    }
}
GET
api.wavv.com/v2/users/userId


Response Properties

Name Type Description
id string Unique ID
firstName string First name
lastName string Last name
email string Email address
phone string Phone number
address1 string Address
address2 string Address line 2
city string City
state string State
zip string Zip
test boolean Testing account
subscriptions object Subscriptions
subscriptions.single boolean Power Dialer Single Line
subscriptions.multi boolean Power Dialer Multiple Line
subscriptions.previewLine boolean Preview Line Dialer
subscriptions.c2c boolean Click to Call Dialer
subscriptions.smsBasic boolean SMS Basic
subscriptions.sms boolean SMS Pro
signedTos object Terms of Service signed
signedTos.DIALER boolean Signed for Dialer
signedTos.SMS boolean Signed for Messenger
signedTos.RVM boolean Signed for Ringless VM
numbers object Phone numbers
numbers.personal array Verified personal numbers
numbers.purchased array Numbers purchased from WAVV


Create User

curl -L -X POST 'https://api.wavv.com/v2/users' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{
    "id": "37128401-4f29-43af-953d-8d800b386a57",
    "firstName": "George",
    "lastName": "Costanza",
    "phone": "9143504210",
    "email": "george@vandelayindustries.com",
    "address1": "1344 Queens Boulevard",
    "city": "Long Island",
    "state": "NY",
    "zip": "11101",
    "test": false,
    "subscriptions": { "single": true, "sms": true }
}'

The above command returns JSON structured like this:

{ "success": true }
POST
api.wavv.com/v2/users


Body Parameters

Name Type Required Description
id string yes Unique ID
firstName string yes First name
lastName string yes Last name
email string yes Email address
phone string no Phone number
address1 string no Address
address2 string no Address line 2
city string no City
state string no State
zip string no Zip
test boolean no Testing account
subscriptions object yes Subscriptions
subscriptions.single boolean no Power Dialer Single Line
subscriptions.multi boolean no Power Dialer Multiple Line
subscriptions.previewLine boolean no Preview Line Dialer
subscriptions.c2c boolean no Click to Call Dialer
subscriptions.smsBasic boolean no SMS Basic
subscriptions.sms boolean no SMS Pro


Update User

curl -L -X PUT 'https://api.wavv.com/v2/users/:userId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{ "subscriptions": { "single": false } }'

The above command returns JSON structured like this:

{ "success": true }
PUT
api.wavv.com/v2/users/userId


Body Parameters

Name Type Required Description
firstName string no First name
lastName string no Last name
email string no Email address
phone string no Phone number
address1 string no Address
address2 string no Address line 2
city string no City
state string no State
zip string no Zip
subscriptions object no Subscriptions
subscriptions.single boolean no Power Dialer Single Line
subscriptions.multi boolean no Power Dialer Multiple Line
subscriptions.previewLine boolean no Preview Line Dialer
subscriptions.c2c boolean no Click to Call Dialer
subscriptions.smsBasic boolean no SMS Basic
subscriptions.sms boolean no SMS Pro


Delete User

curl -L -X DELETE 'https://api.wavv.com/v2/users/:userId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{ "success": true }
DELETE
api.wavv.com/v2/users/userId



Deactivate user and cancel all subscriptions

Voicemails

List Voicemails

curl -L -X GET 'https://api.wavv.com/v2/users/:userId/voicemails' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

[
    {
        "id": "2b954111-3c2b-402c-93d6-f8b1dfa470db",
        "name": "These pretzels are making me thirsty",
        "createdAt": "2024-05-15T05:29:53.619Z",
        "seconds": 15,
        "url": "https://file.wavv.com/messages/3e0d8287540a0252cb0c2b6f19ba3044/8c8ed890-d39a-49b7-a7dc-26dcecf304b0.mp3"
    }
]
GET
api.wavv.com/v2/users/userId/voicemails


Get Voicemail

curl -L -X GET 'https://api.wavv.com/v2/users/:userId/voicemails/:voicemailId' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
    "id": "2b954111-3c2b-402c-93d6-f8b1dfa470db",
    "name": "These pretzels are making me thirsty",
    "createdAt": "2024-05-15T05:29:53.619Z",
    "seconds": 15,
    "url": "https://file.wavv.com/messages/3e0d8287540a0252cb0c2b6f19ba3044/8c8ed890-d39a-49b7-a7dc-26dcecf304b0.mp3"
}
GET
api.wavv.com/v2/users/userId/voicemails/voicemailId

Webhook URL

For more information, see the guide on Webhooks.

Get URL

curl -L -X GET 'https://api.wavv.com/v2/webhook' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{ "url": "https://www.yourapp.com/api/wavv-event" }
GET
api.wavv.com/v2/webhook


Response Properties

Name Type Description
url string Current webhook URL


Set URL

curl -L -X PUT 'https://api.wavv.com/v2/webhook' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json' \
--data-raw '{ "url": "https://www.yourapp.com/api/wavv-event" }'

The above command returns JSON structured like this:

{ "success": true }
PUT
api.wavv.com/v2/webhook


Body Parameters

Name Type Required Description
url string yes URL for webhook events


Delete URL

curl -L -X DELETE 'https://api.wavv.com/v2/webhook' \
-H 'Authorization: Basic base64(VENDOR_ID:API_KEY)' \
-H 'Content-Type: application/json'

The above command returns JSON structured like this:

{ "success": true }
DELETE
api.wavv.com/v2/webhook

Guides

Tokens

import jwt from 'jsonwebtoken';

const issuer = VENDOR_ID;
const signature = API_KEY;

const payload = {
    userId: '37128401-4f29-43af-953d-8d800b386a57',
};

const options = { issuer, expiresIn: 3600 };

const token = jwt.sign(payload, signature, options);

WAVV uses JSON Web Tokens (JWTs) for front-end authentication.

There are two ways to obtain a token:


To generate your own token, follow these steps:


Mini Dialer

The mini dialer is a smaller, alternative dialer widget. The mini dialer floats anywhere on the page and can be repositioned by the user. It can also be minimized to take up less screen real estate. It's ideal for click-to-call, but can be used exclusively.

Activation

Control mini dialer placement with:

<div id="wavv-dialer-mini"></div>

To use the mini dialer, simply set mini to true when calling Start Campaign or Call Phone. Additionally, you can switch between the dial bar and the mini dialer at any time by calling Show Mini. Switching on the fly is not recommended, but can be useful in certain situations (e.g. returning to the list view to load more contacts).

Placement

Control minimized placement with:

<div id="wavv-dialer-minimized"></div>

Unlike the dial bar, the mini dialer does not embed within a div. However, you can use a special div to dictate its initial placement on the page (see example). Similarly, you can use a div to determine where the mini dialer will minimize to. Keep in mind, once the user drags the mini dialer to a new location, that placement will take precedence.

Merge Fields

Add custom merge field options:

import { setMergeFields } from '@wavv/messenger';

setMergeFields({
    fields: [
        { id: 'sqft', label: 'Square Feet' },
        { id: 'neighborhood', label: 'Neighborhood' },
    ],
});
const { setMergeFields } = window.WavvMessenger;

setMergeFields({
    fields: [
        { id: 'sqft', label: 'Square Feet' },
        { id: 'neighborhood', label: 'Neighborhood' },
    ],
});

Then provide values in each contact object:

{
    "contactId": "0c3322de-9cbe-4916-8404-8ed5c427bdfa",
    "mergeFields": [
        { "id": "sqft", "value": "4,000" },
        { "id": "neighborhood", "value": "Briarwood" }
    ]
}

WAVV allows you to add custom merge fields.

To get started with this:


Default Merge Fields

ID Label
name Full Name
first_name First Name
last_name Last Name
address Address
city City

Test Numbers

Send a message to (958) 555-1234:

Hello.

And it will echo back:

Hello.

WAVV provides several phone numbers for reliable, deterministic testing.

The last four digits of these numbers can be anything you want.


Number Calling Behavior Texting Behavior
(958) 555-XXXX Echos call audio Echos message body
(958) 666-XXXX Rings endlessly (no answer) No response
(958) 888-XXXX Plays voicemail greeting No response
(958) 777-XXXX Plays voice recording No response
(958) 444-XXXX Answers, quickly hangs up Delivery fails
(958) 000-XXXX Answers, presses 1, holds the line No response

Test Credit Cards

To enable test cards, prefix the user ID with testing:

{ "userId": "testing:37128401-4f29-43af-953d-8d800b386a57" }

WAVV provides several credit card numbers for testing.


Card Card Number CVV Expiration
Visa 4242 4242 4242 4242 Any 3 digits Any future date
Amex 3782 822463 10005 Any 4 digits Any future date
Mastercard 5555 5555 5555 4444 Any 3 digits Any future date
Discover 6011 1111 1111 1117 Any 3 digits Any future date
Diners Club 3056 9300 0902 0004 Any 3 digits Any future date

REST API

Authentication

import axios from 'axios';

axios({
    method: 'PUT',
    url: 'https://api.wavv.com/v2/example',
    auth: {
        username: VENDOR_ID,
        password: API_KEY,
    },
    data: {
        email: 'george@vandelayindustries.com',
    },
});

All endpoints expect Basic Auth as follows:

Failure to authenticate will return status code 401.

Requests

Successful requests return data or an object of the form:

{ "success": true }

POST and PUT requests should be JSON encoded.

Ensure your Content-Type header is application/json.

Responses

Failed requests return an object of the form:

{ "success": false, "error": "Human-readable explanation" }

All responses will be a JSON object or array.

Status code will be one of: 200, 400, 404, or 500.

Webhooks

Configuration

To subscribe to webhook events, simply set your Webhook URL.

Requests

Webhook events will then POST to your URL.

The body will be a JSON object of the form {type, payload}.

For a list of event types and payloads, see Webhook Events.

Responses

Your server should respond with status code 200.

Failed requests will retry 10 times with exponential backoff.

Validation

On the request, you'll see a header called X-WAVV-Signature.

This is a SHA-256 hash of the request body concatenated with your API Key.

Data

Types



Contact

{
    "contactId": "0c3322de-9cbe-4916-8404-8ed5c427bdfa",
    "numbers": ["9143504210", "9143505590"],
    "firstName": "George",
    "lastName": "Costanza",
    "name": "George Louis Costanza",
    "address": "1344 Queens Boulevard",
    "city": "Long Island",
    "avatarUrl": "https://wavv-public.s3.amazonaws.com/docs/summer/george.jpg",
    "subheading": "Architect",
    "mergeFields": [
        { "id": "sqft", "value": "4,000" },
        { "id": "neighborhood", "value": "Briarwood" }
    ]
}

Properties

Name Type Description
contactId string Unique ID
numbers array Phone numbers
firstName string First name
lastName string Last Name
name string Display name
address string Address
city string City
avatarUrl string Image URL for avatar
subheading string Displayed under name
mergeFields array Custom merge field data
mergeFields[].id string Merge field ID
mergeFields[].value string Merge field value

Enumerations



Brand Status

Enum Values

Name Description
NONE Registration not submitted
PENDING Registration is being reviewed
APPROVED Registration was approved
FAILED Registration was rejected



Call Outcome

import {
    CALL_OUTCOME_HUNG_UP,
    CALL_OUTCOME_USER_HUNG_UP,
    CALL_OUTCOME_NO_ANSWER,
    CALL_OUTCOME_BUSY,
    CALL_OUTCOME_DISCONNECTED,
    CALL_OUTCOME_CALLBACK,
    CALL_OUTCOME_VOICEMAIL,
    CALL_OUTCOME_NO_CALLBACK,
    CALL_OUTCOME_NO_VOICEMAIL,
    CALL_OUTCOME_UNKNOWN,
} from '@wavv/dialer';
const {
    CALL_OUTCOME_HUNG_UP,
    CALL_OUTCOME_USER_HUNG_UP,
    CALL_OUTCOME_NO_ANSWER,
    CALL_OUTCOME_BUSY,
    CALL_OUTCOME_DISCONNECTED,
    CALL_OUTCOME_CALLBACK,
    CALL_OUTCOME_VOICEMAIL,
    CALL_OUTCOME_NO_CALLBACK,
    CALL_OUTCOME_NO_VOICEMAIL,
    CALL_OUTCOME_UNKNOWN,
} = window.WavvDialer;

Enum Values

Name Description
HUNG_UP Callee hung up the line
USER_HUNG_UP User hung up the line
NO_ANSWER Call was not answered
BUSY Line was busy
DISCONNECTED Number was disconnected
CALLBACK Callback message was played
VOICEMAIL Voicemail message was played
NO_CALLBACK A callback message would have been played if the user had one recorded
NO_VOICEMAIL A voicemail message would have been played if the user had one recorded
UNKNOWN Call ended, but no one knows why



DNC Type

import {
    DNC_TYPE_MANUAL,
    DNC_TYPE_IVR_OPT_OUT,
    DNC_TYPE_SMS_OPT_OUT,
} from '@wavv/dialer';
const {
    DNC_TYPE_MANUAL,
    DNC_TYPE_IVR_OPT_OUT,
    DNC_TYPE_SMS_OPT_OUT,
} = window.WavvDialer;

Enum Values

Name Description
MANUAL Manually added
IVR_OPT_OUT Opt-opt via IVR prompt
SMS_OPT_OUT Opt-out via SMS STOP word

Webhook Events



Call Forwarded

CALL_FORWARDED

{
    "type": "CALL_FORWARDED",
    "payload": {
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "phone": "8444545111",
        "destination": "9143504210"
    }
}

Payload Properties

Name Type Description
userId string User ID
phone string User phone number
destination string Destination phone number



Call Recorded

CALL_RECORDED

{
    "type": "CALL_RECORDED",
    "payload": {
        "id": "d995d0ef-4b7a-4ccb-af50-f884c8a87053",
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "number": "9143504210",
        "contactId": "0c3322de-9cbe-4916-8404-8ed5c427bdfa",
        "duration": 327,
        "startTime": "2022-02-04T14:22:56.301Z"
    }
}

Payload Properties

Name Type Description
id string Recording ID
userId string User ID
number string Destination phone number
contactId string Contact ID of destination phone number
duration number Duration of recording in seconds
startTime string Start time of recording



Message Failed

MESSAGE_FAILED

{
    "type": "MESSAGE_FAILED",
    "payload": {
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "to": "9143504210",
        "from": "8444545111",
        "body": "Hello, Newman.",
        "blastId": "67740096-b017-4687-8fc8-dfeb7756a1de"
    }
}

Payload Properties

Name Type Description
userId string User ID
to string Receiving phone number
from string User phone number
body string Body of the message
blastId string Associated blast (if applicable)



Message Received

MESSAGE_RECEIVED

{
    "type": "MESSAGE_RECEIVED",
    "payload": {
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "to": "8444545111",
        "from": "9143504210",
        "body": "Hello, Jerry."
    }
}

Payload Properties

Name Type Description
userId string User ID
to string User phone number
from string Sending phone number
body string Body of the message



Message Sent

MESSAGE_SENT

{
    "type": "MESSAGE_SENT",
    "payload": {
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "to": "9143504210",
        "from": "8444545111",
        "body": "Hello, Newman.",
        "blastId": "ae67c1e6-0006-4ef3-b013-67bcc2f0497b"
    }
}

Payload Properties

Name Type Description
userId string User ID
to string Receiving phone number
from string User phone number
body string Body of the message
blastId string Associated blast (if applicable)



Subscription Changed

SUBSCRIPTION_CHANGED

{
    "type": "SUBSCRIPTION_CHANGED",
    "payload": {
        "userId": "37128401-4f29-43af-953d-8d800b386a57",
        "subscriptions": { "multi": true }
    }
}

Payload Properties

Name Type Description
userId string User ID
subscriptions object Subscriptions
subscriptions.single boolean Power Dialer Single Line
subscriptions.multi boolean Power Dialer Multiple Line
subscriptions.previewLine boolean Preview Line Dialer
subscriptions.smsBasic boolean SMS Basic
subscriptions.sms boolean SMS Pro