@ dialstack/ sdk

官方 JavaScript SDK 为 拨号 - 商业之声的垂直SaaS.

将语音能力直接嵌入您的应用程序中, 并带有用于调用日志、 语音邮件等的即时反应组件 .

安装

npm install @dialstack/sdk

快速启动

反应

import { loadDialstackAndInitialize } from '@dialstack/sdk';
import { DialstackComponentsProvider, CallLogs, Voicemails } from '@dialstack/sdk/react';
import { useEffect, useState } from 'react';
import type { DialStackInstance } from '@dialstack/sdk';

function App() {
  const [dialstack, setDialstack] = useState<DialStackInstance | null>(null);

  useEffect(() => {
    // Initialize DialStack with your publishable key and session fetcher
    loadDialstackAndInitialize({
      publishableKey: 'pk_live_YOUR_PUBLISHABLE_KEY',
      fetchClientSecret: async () => {
        const res = await fetch('https://your-backend.com/api/create-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ accountId: 'acct_123' }),
        });
        const data = await res.json();
        return data.client_secret;
      },
    }).then(setDialstack);
  }, []);

  if (!dialstack) {
    return <div>Loading...</div>;
  }

  return (
    <DialstackComponentsProvider dialstack={dialstack}>
      <div>
        <h1>My Voice Dashboard</h1>
        <CallLogs />
        <Voicemails />
      </div>
    </DialstackComponentsProvider>
  );
}

香草 Java 脚本

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@dialstack/sdk"></script>
  </head>
  <body>
    <dialstack-call-logs></dialstack-call-logs>
    <dialstack-voicemails></dialstack-voicemails>

    <script>
      // Initialize DialStack with session fetcher
      DialStack.loadDialstackAndInitialize({
        publishableKey: 'pk_live_YOUR_PUBLISHABLE_KEY',
        fetchClientSecret: async () => {
          const res = await fetch('https://your-backend.com/api/create-session', {
            method: 'POST',
            body: JSON.stringify({ accountId: 'acct_123' }),
          });
          const data = await res.json();
          return data.client_secret;
        },
      });
    </script>
  </body>
</html>

构成部分

调用日志

显示调用历史列表, 包括调用者、 持续时间和状态等细节 .

<CallLogs
  dateRange={{ start: '2025-01-01', end: '2025-01-31' }}
  limit={50}
  onRowClick={(e) => console.log('Selected call:', e.callId)}
  onLoadError={(e) => console.error(e.error)}
/>

道具 :

• dateRange - 按日期范围过滤({ start?: string, end?: string }(中文(简体) )
• limit - 要显示的最大记录( 默认: 20)
• locale - 用户界面字符串的自定义区域
• formatting - 日期/电话格式化选项
• onLoaderStart - 开始装入时召回
• onLoadError - 装入失败时召回
• onPageChange - 当页形变化时召回
• onRowClick - 单击一行时召回

语音信箱

显示带有回放控件的语音邮件列表 .

<Voicemails
  userId="user-uuid-123"
  onVoicemailSelect={(e) => console.log('Selected:', e.voicemailId)}
  onCallBack={(e) => initiateCall(e.phoneNumber)}
/>

道具 :

• userId - 获取语音邮件的用户ID( 需要)
• locale - 用户界面字符串的自定义区域
• formatting - 日期/电话格式化选项
• onLoaderStart - 开始装入时召回
• onLoadError - 装入失败时召回
• onVoicemailSelect - 选定语音信箱时召回
• onVoicemailPlay - 重播开始后召回
• onVoicemailPause - 回放暂停时召回
• onVoicemailDelete - 语音信箱被删除时召回
• onCallBack - 点击回调按钮时回调

他们

使用 CSS 变量自定义组件外观 appearance 初始化时的选项 :

const dialstack = await loadDialstackAndInitialize({
  publishableKey: 'pk_live_YOUR_KEY',
  fetchClientSecret: async () => {
    /* ... */
  },
  appearance: {
    theme: 'light', // 'light' | 'dark' | 'auto'
    variables: {
      // Colors
      colorPrimary: '#6772E5',
      colorBackground: '#ffffff',
      colorText: '#1a1a1a',
      colorDanger: '#e5484d',
      colorSuccess: '#30a46c',

      // Typography
      fontFamily: 'Inter, system-ui, sans-serif',
      fontSizeBase: '14px',

      // Spacing
      spacingUnit: '8px',
      borderRadius: '4px',
    },
  },
});

所有组件都继承了SDK实例的外观并自动为轻/暗主题调整.

国际化(i18n)

组成部分支持通过下列途径实现国际化: locale 道具 :

import { en } from '@dialstack/sdk/locales';

// Create a custom locale by extending the default
const fr: typeof en = {
  common: {
    loading: 'Chargement...',
    error: 'Erreur',
    // ... other translations
  },
  callLogs: {
    title: 'Journal des appels',
    // ... other translations
  },
  voicemails: {
    title: 'Messagerie vocale',
    // ... other translations
  },
};

<CallLogs locale={fr} />;

格式化

自定义日期和电话号码格式:

<CallLogs
  formatting={{
    defaultCountry: 'FR', // ISO 3166-1 alpha-2 country code
    dateLocale: 'fr-FR', // BCP 47 language tag
    use24HourTime: true, // 24-hour format
    showTimezone: false, // Hide timezone
  }}
/>

处理错误

SDK为优雅地处理错误提供回调:

<CallLogs
  onLoaderStart={({ elementTagName }) => {
    console.log(`Loading ${elementTagName}...`);
  }}
  onLoadError={({ error, elementTagName }) => {
    console.error(`Error in ${elementTagName}:`, error);
    // Show user-friendly error message or retry logic
  }}
/>

提供者出错

如果你忘了把部件包起来 DialstackComponentsProvider,你会得到一个有用的错误信息:

Error: Could not find DialStack context; You need to wrap your app
in a <DialstackComponentsProvider> provider.
See https://docs.dialstack.ai/sdk/react for setup instructions.

网络错误

组件自动处理网络错误并显示错误状态. 使用 onLoadError 调用以执行自定义错误处理、重试逻辑或错误报告.

无障碍

所有组件都考虑到无障碍性:

• ARIA 标签页:1 role, (中文(简体) ), aria-label,以及 aria-live 属性
• 键盘导航: 完整的键盘支持(Tab, Enter, Space)
• 重点管理: 通过 CSS 变量可见焦点环
• 屏幕阅读器支持: 装入/误入状态状态通知

API 参考

loadDialstackAndInitialize(options)

以您可公布的密钥和会话获取器初始化 DialStack SDK .

参数:

• options.publishableKey (字符串, 需要): 您的 DialStack 可发布密钥( 起始于 pk_live_ 或者说 pk_test_(中文(简体) )
• options.fetchClientSecret (职能,要求): 从后端获取客户端机密的 Async 函数 。 可以返回字符串或 { clientSecret, expiresAt }。 。 。 .
• options.appearance (对象,可选): 主题选项
• options.apiUrl (字符串,可选):自定义 API 端点 URL

回返情况: Promise<DialStackInstance>

DialstackComponentsProvider

反应上下文提供者,使DialStack实例和客户端秘密提供给儿童组件.

道具 :

• dialstack (拨号系统,需要): 从 DialStack 实例 loadDialstackAndInitialize()
• children (反应节点,需要): 儿童成分

认证

SDK使用账户范围会议进行认证. 你必须:

1. 使用 DialStack API 调用您的后端创建会话 :

   POST https://api.dialstack.ai/v1/account_sessions
   Authorization: Bearer sk_live_YOUR_SECRET_KEY
   DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41
   Content-Type: application/json
   

2. 提供a fetchClientSecret 呼叫时回调 loadDialstackAndInitialize() 返回一个 client_secret 从你的后端.

1小时后,会议结束。 SDK 使用 fetchClientSecret 调用.

安全说明:只有服务器侧API键才能创建会话. 无法使用会话符号创建新会话, 防止未经授权的会话扩展 .

浏览器兼容性

SDK支持所有现代浏览器:

所需经费:

• ES2015+(ES6)支持
• Web 组件 v1( 自定义元素, 阴影 DOM)
• 获取 API

说明: 不支持 Internet Explorer .

文档

完整的文件可在 https://docs.dialstack.ai (英语)

支助

• 文档
• GitHub 问题
• GitHub 讨论

许可证

麻省理工学院-见 自由主义 详情