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:
- 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
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
callPhone
now requires acontact
objectstartCampaign
andcallPhone
now supportmini
property
v3.0.0
- Added
groupId
andsubgroupId
toinit
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
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:
- Install it with npm
- Load it with a script tag
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
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
andsubgroupId
toinit
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'
The above command returns JSON structured like this:
{ "status": "APPROVED" }
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"
}
]
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 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"
}
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 }
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"
}
]
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" }
]
}
]
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 }
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"
}
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
}
]
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
}
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": []
}
]
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": []
}
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" }
}
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 }
}
]
Response Properties
Name | Type | Description |
---|---|---|
id | string | Unique ID |
firstName | string | First name |
lastName | string | Last name |
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"]
}
}
Response Properties
Name | Type | Description |
---|---|---|
id | string | Unique ID |
firstName | string | First name |
lastName | string | Last name |
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 }
Body Parameters
Name | Type | Required | Description |
---|---|---|---|
id | string | yes | Unique ID |
firstName | string | yes | First name |
lastName | string | yes | Last name |
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 }
Body Parameters
Name | Type | Required | Description |
---|---|---|---|
firstName | string | no | First name |
lastName | string | no | Last name |
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 }
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 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"
}
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" }
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 }
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 }
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:
- 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
)
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:
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
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:
- Username: Vendor ID
- Password: API Key
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 |