dialstack-voicemails

The voicemails Web Component displays a list of voicemails with audio playback and actions.

Usage

<dialstack-voicemails></dialstack-voicemails>

<script>
  const element = document.querySelector('dialstack-voicemails');
  element.setUserId('user_123');
  element.setClientSecret('cs_live_...');
</script>

Required: User ID

You must call setUserId() before the component will load data.

Automatic Pagination

Pagination is handled automatically by the component using cursor-based pagination. You don't need to manage cursors or page state manually. The component automatically loads more voicemails as needed. See the Pagination Guide for details.

Methods

Common Methods

Method	Parameters	Description
setClientSecret	secret: string	Set session token
setInstance	instance: DialStackInstance	Set SDK instance
setLocale	locale: Locale	Set UI strings
setFormatting	options: FormattingOptions	Set date/phone formatting
setIcons	icons: ComponentIcons	Set custom SVG icons
setLayoutVariant	variant: 'compact' | 'comfortable' | 'default'	Set layout density
setClasses	classes: VoicemailsClasses	Set CSS classes
setOnLoaderStart	callback: (event) => void	Set loading callback
setOnLoadError	callback: (event) => void	Set error callback

Voicemails-Specific Methods

Method	Parameters	Description
setUserId	userId: string	Required. Set user ID
setDisplayOptions	options: VoicemailDisplayOptions	Show/hide UI elements
setBehaviorOptions	options: VoicemailBehaviorOptions	Configure behavior
setCustomRowRenderer	renderer: (voicemail) => string	Custom row HTML
setOnVoicemailSelect	callback: (event) => void	Selection callback
setOnVoicemailPlay	callback: (event) => void	Play callback
setOnVoicemailPause	callback: (event) => void	Pause callback
setOnVoicemailDelete	callback: (event) => void	Delete callback
setOnCallBack	callback: (event) => void	Call back callback
setOnDeleteRequest	callback: (id) => Promise<boolean>	Custom delete confirm

Configuration Examples

Display Options

const voicemails = document.querySelector('dialstack-voicemails');

voicemails.setDisplayOptions({
  showDuration: true,
  showTranscription: true,
  showCallbackButton: true,
  showDeleteButton: true,
  showProgressBar: true,
  showTimestamp: true,
});

Behavior Options

voicemails.setBehaviorOptions({
  autoPlayOnExpand: true,
  confirmBeforeDelete: true,
  markAsReadOnPlay: true,
  allowSeeking: true,
});

Formatting

voicemails.setFormatting({
  defaultCountry: 'US',
  dateLocale: 'en-US',
  use24HourTime: false,
  showTimezone: false,
});

Layout and Styling

voicemails.setLayoutVariant('comfortable');

voicemails.setClasses({
  base: 'my-voicemails',
  list: 'my-list',
  item: 'my-item',
  itemExpanded: 'my-item--expanded',
  itemUnread: 'my-item--unread',
  player: 'my-player',
  actions: 'my-actions',
});

Event Handlers

onVoicemailSelect

voicemails.setOnVoicemailSelect((event) => {
  console.log('Selected:', event.voicemailId);
});

onVoicemailPlay / onVoicemailPause

voicemails.setOnVoicemailPlay((event) => {
  console.log('Playing:', event.voicemailId);
});

voicemails.setOnVoicemailPause((event) => {
  console.log('Paused:', event.voicemailId);
});

onCallBack

voicemails.setOnCallBack((event) => {
  console.log('Call back:', event.phoneNumber);
  // Initiate call
  window.location.href = `tel:${event.phoneNumber}`;
});

onDeleteRequest

Custom delete confirmation:

voicemails.setOnDeleteRequest(async (voicemailId) => {
  // Show custom modal
  const confirmed = await showConfirmModal('Delete voicemail?');
  return confirmed; // Return true to delete, false to cancel
});

onVoicemailDelete

voicemails.setOnVoicemailDelete((event) => {
  console.log('Deleted:', event.voicemailId);
  showNotification('Voicemail deleted');
});

Custom Row Renderer

voicemails.setCustomRowRenderer((voicemail) => {
  const unreadClass = voicemail.is_read ? '' : 'unread';
  const duration = formatDuration(voicemail.duration_seconds);

  return `
    <div class="voicemail-row ${unreadClass}">
      <div class="caller">
        <strong>${voicemail.from_name || 'Unknown'}</strong>
        <span>${voicemail.from_number}</span>
      </div>
      <div class="meta">
        <span class="duration">${duration}</span>
        <span class="date">${new Date(voicemail.created_at).toLocaleDateString()}</span>
      </div>
      ${
        voicemail.transcription
          ? `
        <div class="transcription">${voicemail.transcription}</div>
      `
          : ''
      }
    </div>
  `;
});

Complete Example

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@dialstack/sdk"></script>
    <style>
      .voicemail-inbox {
        max-width: 600px;
        margin: 0 auto;
        padding: 20px;
      }
      h1 {
        margin-bottom: 20px;
      }
    </style>
  </head>
  <body>
    <div class="voicemail-inbox">
      <h1>Voicemail Inbox</h1>
      <dialstack-voicemails></dialstack-voicemails>
    </div>

    <script>
      // Initialize
      const dialstack = DialStack.initialize({
        publishableKey: 'pk_live_YOUR_KEY',
        appearance: {
          theme: 'auto',
          variables: {
            colorPrimary: '#6772E5',
          },
        },
      });

      // Get element
      const voicemails = document.querySelector('dialstack-voicemails');

      // Required: Set user ID
      voicemails.setUserId('user_123');

      // Configure display
      voicemails.setDisplayOptions({
        showDuration: true,
        showTranscription: true,
        showCallbackButton: true,
        showDeleteButton: true,
        showProgressBar: true,
        showTimestamp: true,
      });

      // Configure behavior
      voicemails.setBehaviorOptions({
        autoPlayOnExpand: true,
        confirmBeforeDelete: true,
        markAsReadOnPlay: true,
        allowSeeking: true,
      });

      // Formatting
      voicemails.setFormatting({
        defaultCountry: 'US',
        use24HourTime: false,
      });

      // Layout
      voicemails.setLayoutVariant('comfortable');

      // Event handlers
      voicemails.setOnVoicemailSelect((event) => {
        console.log('Selected:', event.voicemailId);
      });

      voicemails.setOnVoicemailPlay((event) => {
        console.log('Playing:', event.voicemailId);
      });

      voicemails.setOnCallBack((event) => {
        if (confirm(`Call ${event.phoneNumber}?`)) {
          window.location.href = `tel:${event.phoneNumber}`;
        }
      });

      voicemails.setOnVoicemailDelete((event) => {
        console.log('Deleted:', event.voicemailId);
      });

      voicemails.setOnLoadError((event) => {
        console.error('Load error:', event.error);
        alert('Failed to load voicemails');
      });

      // Fetch session and activate
      fetch('/api/dialstack/session', { method: 'POST' })
        .then((res) => res.json())
        .then((session) => {
          voicemails.setClientSecret(session.client_secret);
        });
    </script>
  </body>
</html>

Next Steps

• call-logs Element - Call logs reference
• Theming - Customize appearance
• i18n - Internationalization