Welcome


@@@@@@@        @@@         @@@@@@       @@@       @@@@@@@         @@@@@@    @@@@@@@        @@@@@@@
 @@@@@@@      @@@@@      @@@@@@@       @@@@@@      @@@@@@@      @@@@@@@      @@@@@@@      @@@@@@@
  @@@@@@@    @@@@@@@@   @@@@@@@       @@@@@@@@       @@@@@@@   @@@@@@@        @@@@@@@    @@@@@@
   @@@@@@@ @@@@@@@@@@@ @@@@@@@       @@@@@@@@@@       @@@@@@@ @@@@@@@          @@@@@@@ @@@@@@@
    @@@@@@@@@@@@@@@@@@@@@@@@@      @@@@@@@@@@@@@       @@@@@@@@@@@@@            @@@@@@@@@@@@@
      @@@@@@@@@@ @@@@@@@@@@@      @@@@@@@  @@@@@@       @@@@@@@@@@                @@@@@@@@@@
       @@@@@@@@   @@@@@@@@       @@@@@@@    @@@@@@@      @@@@@@@@                  @@@@@@@@
        @@@@@       @@@@@       @@@@@@@      @@@@@@@       @@@@@                    @@@@@
         @@@         @@@       @@@@@@@        @@@@@@@       @@@                      @@@

{ "title": "WAVV Docs", "lastUpdated": "2025-02-11T07:08:17.217Z" }

Welcome to WAVV's developer documentation!

Ready to supercharge your app?

Learn about our communication widgets:

Dialer
Messenger

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

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:

Install it with npm
Load it with a script tag

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

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

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

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

callPhone({
    number: '9143504210',
    contact: {
        contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
});

const { callPhone } = window.WavvDialer;

callPhone({
    number: '9143504210',
    contact: {
        contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        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.

init only needs to be called once (across all widgets)

To avoid race conditions, await the call to init

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.

Make sure to call openSettings from the widget that matches your use case

Start Campaign

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

const contacts = [
    {
        contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
        address: '1344 Queens Boulevard',
        city: 'Long Island',
    },
];

startCampaign({ contacts });

const { startCampaign } = window.WavvDialer;

const contacts = [
    {
        contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        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: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
});

const { callPhone } = window.WavvDialer;

callPhone({
    number: '9143504210',
    contact: {
        contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        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: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
});

const { addPhone } = window.WavvDialer;

addPhone({
    number: '9143504210',
    contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
});

Adds a number to a contact in the campaign.

Parameters

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

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: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
    hangup: true,
    resume: true,
});

const { removeContact } = window.WavvDialer;

removeContact({
    contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
    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: '92407cee-1939-445d-bb33-c27e968eeab3' });

const { dropVoicemail } = window.WavvDialer;

dropVoicemail({ id: '92407cee-1939-445d-bb33-c27e968eeab3' });

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.

focused is the easiest way to determine the current contact and number

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

callPhone now requires a contact object
startCampaign and callPhone now support mini property

v3.0.0

Added groupId and subgroupId to init

v2.5.0

Added openSettings

v2.4.0

Added endCampaign
Added documentation for close

v2.3.0

Added purchaseDialer
Added listVoicemails
Added dropVoicemail
Added recordCall
Added close

v2.1.0

Added addOverlayVisibleListener
Added addClosedListener
Added addManageSubscriptionListener
Added addUpsellClickListener

v2.0.0

TypeScript support
Added init
Added setTheme

Messenger

Latest version: 3.0.1

Quick Start

To get started, follow these simple steps:

1. Include

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:

Install it with npm
Load it with a script tag

2. Initialize

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

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

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.

init only needs to be called once (across all widgets)

To avoid race conditions, await the call to init

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.

Make sure to call openSettings from the widget that matches your use case

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: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        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: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        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: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        numbers: ['9143504210', '9143505590'],
        firstName: 'George',
        lastName: 'Costanza',
    },
];

startBlast({ contacts });

const { startBlast } = window.WavvMessenger;

const contacts = [
    {
        contactId: 'ca25260f-7688-4fd1-a537-d199035f4bb5',
        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

Contact Search

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

Contact Link

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.

Properties

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

Added groupId and subgroupId to init

v2.4.0

Added openSettings

v2.3.1

Fixed ContactSearch type

v2.3.0

Added purchaseMessenger
Added close

v2.1.0

Added addOverlayVisibleListener
Added addManageSubscriptionListener
Added addUpsellClickListener

v2.0.0

TypeScript support
Added init
Added setTheme

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'

{ "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'

[
    {
        "id": "3df20a06-1029-479a-8a03-c47510fef66e",
        "number": "9143505590",
        "type": "MANUAL",
        "createdAt": "2025-02-11T06:07:02.826Z"
    }
]

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'

[
    {
        "id": "117502a5-ce23-4319-a631-55f5ec808eb6",
        "contactId": "ca25260f-7688-4fd1-a537-d199035f4bb5",
        "date": "2025-02-10T21:34:20.777Z",
        "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'

{
    "id": "117502a5-ce23-4319-a631-55f5ec808eb6",
    "contactId": "ca25260f-7688-4fd1-a537-d199035f4bb5",
    "date": "2025-02-10T21:34:20.777Z",
    "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'

{ "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'

[
    {
        "number": "9143504210",
        "createdAt": "2025-02-10T17:23:41.998Z",
        "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

If you dont specify a userId, the numbers listed will be for A2P texting

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" }'

[
    {
        "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" }'

{ "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." }'

{
    "success": true,
    "messageId": "4ebbd630-c388-4017-bebb-174758367aa9",
    "threadId": "df4dc9ee-2ecd-44a0-86aa-f289dc7096cf"
}

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

You must specify either a from A2P number or userId. threadId will not be returned if you are not specifying a userId.

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'

[
    {
        "id": "65a46c3e-1787-4946-8c81-807ffd2cddcc",
        "userId": "9b449b5c-4a85-460d-a335-e66461003913",
        "displayName": "Alice Answer",
        "displayNameLocked": false,
        "recipientCount": 1,
        "avatarUrl": "",
        "type": "NORMAL",
        "draft": false,
        "preview": "Hello, Newman.",
        "previewStatus": "SENT",
        "unreadCount": 0,
        "sortTime": "2025-02-10T15:44:23.030Z",
        "createdAt": "2024-08-27T21:59:55.100Z",
        "updatedAt": "2025-02-10T20:44:10.268Z",
        "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'

{
    "id": "71c78f75-1d94-4274-926e-c9bf9e79cd22",
    "userId": "9b449b5c-4a85-460d-a335-e66461003913",
    "displayName": "Alice Answer",
    "displayNameLocked": false,
    "recipientCount": 1,
    "avatarUrl": "",
    "type": "NORMAL",
    "draft": false,
    "preview": "Hello, Newman.",
    "previewStatus": "SENT",
    "unreadCount": 0,
    "sortTime": "2025-02-10T15:17:03.623Z",
    "createdAt": "2024-12-24T08:02:58.487Z",
    "updatedAt": "2025-02-10T14:58:52.211Z",
    "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'

[
    {
        "id": "912e4aab-ee5b-4d6f-9d2d-76ccf8287c9f",
        "appId": "432a510b-674f-478d-9d73-69afe7a4183e",
        "userId": "9b449b5c-4a85-460d-a335-e66461003913",
        "type": "NORMAL",
        "draft": false,
        "status": "SENT",
        "body": "Hello, Newman.",
        "rawBody": "Hello, Newman.",
        "mergeFields": [],
        "mergeFailed": false,
        "unread": false,
        "scheduledAt": "2025-02-10T22:10:39.200Z",
        "sortTime": "2025-02-10T18:58:50.375Z",
        "createdAt": "2025-02-10T21:38:59.970Z",
        "updatedAt": "2025-02-10T08:21:06.282Z",
        "authorId": "9b449b5c-4a85-460d-a335-e66461003913",
        "recipientId": null,
        "omitted": false,
        "hidden": false,
        "attachments": [],
        "deleted": false,
        "thread": {
            "id": "1462b936-85e3-4807-b942-0dfa1e1b7736",
            "userId": "9b449b5c-4a85-460d-a335-e66461003913",
            "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'

{
    "id": "eb8f2f58-0e37-4a33-99ac-e00bfa2de7a5",
    "appId": "5a8ff440-38af-4f58-ba92-766b81d6623a",
    "userId": "9b449b5c-4a85-460d-a335-e66461003913",
    "type": "NORMAL",
    "draft": false,
    "status": "SENT",
    "body": "Hello, Newman.",
    "rawBody": "Hello, Newman.",
    "mergeFields": [],
    "mergeFailed": false,
    "unread": false,
    "scheduledAt": "2025-02-11T06:27:06.228Z",
    "sortTime": "2025-02-11T04:29:59.485Z",
    "createdAt": "2025-02-10T16:22:22.196Z",
    "updatedAt": "2025-02-10T09:41:50.515Z",
    "authorId": "9b449b5c-4a85-460d-a335-e66461003913",
    "recipientId": null,
    "omitted": false,
    "hidden": false,
    "attachments": [],
    "deleted": false,
    "thread": {
        "id": "1c36feb3-6644-407c-a50e-c6fcfa1989c7",
        "userId": "9b449b5c-4a85-460d-a335-e66461003913",
        "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": "9b449b5c-4a85-460d-a335-e66461003913" }'

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "payload": { "userId": "9b449b5c-4a85-460d-a335-e66461003913" }
}

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'

[
    {
        "id": "9b449b5c-4a85-460d-a335-e66461003913",
        "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'

{
    "id": "9b449b5c-4a85-460d-a335-e66461003913",
    "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": "9b449b5c-4a85-460d-a335-e66461003913",
    "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 }
}'

{ "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 } }'

{ "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'

{ "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'

[
    {
        "id": "92407cee-1939-445d-bb33-c27e968eeab3",
        "name": "These pretzels are making me thirsty",
        "createdAt": "2025-02-10T16:37:24.117Z",
        "seconds": 15,
        "url": "https://file.wavv.com/messages/3e0d8287540a0252cb0c2b6f19ba3044/e7650410-2a8a-4e51-aa53-2634e6c63c14.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'

{
    "id": "92407cee-1939-445d-bb33-c27e968eeab3",
    "name": "These pretzels are making me thirsty",
    "createdAt": "2025-02-10T16:37:24.117Z",
    "seconds": 15,
    "url": "https://file.wavv.com/messages/3e0d8287540a0252cb0c2b6f19ba3044/e7650410-2a8a-4e51-aa53-2634e6c63c14.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'

{ "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" }'

{ "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'

{ "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: '9b449b5c-4a85-460d-a335-e66461003913',
};

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:

Use the Create Token REST API
Generate one yourself

To generate your own token, follow these steps:

Set the issuer to your Vendor ID
Provide the userId in the JWT payload
Sign the JWT with your API Key (algorithm HS256)

Important note about users: If we're handling billing, you can pass us a userId we don't know about yet. They will be treated as a new user and prompted to purchase a subscription. However, if you've chosen to handle billing, the user must exist in our system first. Keep this in mind, as you might need to create the user before authenticating.

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

<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

<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

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' },
    ],
});

{
    "contactId": "ca25260f-7688-4fd1-a537-d199035f4bb5",
    "mergeFields": [
        { "id": "sqft", "value": "4,000" },
        { "id": "neighborhood", "value": "Briarwood" }
    ]
}

WAVV allows you to add custom merge fields.

To get started with this:

Add custom options with Set Merge Fields
Provide values for those options in your contact data

Default Merge Fields

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

Test Numbers

Hello.

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

{ "userId": "testing:9b449b5c-4a85-460d-a335-e66461003913" }

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

Test cards only work when the user ID is prefixed with testing:

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:

Username: Vendor ID
Password: API Key

Failure to authenticate will return status code 401.

Requests

{ "success": true }

POST and PUT requests should be JSON encoded.

Ensure your Content-Type header is application/json.

Responses

{ "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": "ca25260f-7688-4fd1-a537-d199035f4bb5",
    "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": "9b449b5c-4a85-460d-a335-e66461003913",
        "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": "76fb2d71-7f31-4e1b-b730-0fee63f7630c",
        "userId": "9b449b5c-4a85-460d-a335-e66461003913",
        "number": "9143504210",
        "contactId": "ca25260f-7688-4fd1-a537-d199035f4bb5",
        "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": "9b449b5c-4a85-460d-a335-e66461003913",
        "to": "9143504210",
        "from": "8444545111",
        "body": "Hello, Newman.",
        "blastId": "ef23c35e-d41a-4f9d-9b4e-89dd2eea51c6"
    }
}

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": "9b449b5c-4a85-460d-a335-e66461003913",
        "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": "9b449b5c-4a85-460d-a335-e66461003913",
        "to": "9143504210",
        "from": "8444545111",
        "body": "Hello, Newman.",
        "blastId": "74f9d0ca-7b6c-4853-b707-7840c9e7dec1"
    }
}

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": "9b449b5c-4a85-460d-a335-e66461003913",
        "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