BuilderBot Documentation

BuilderBot is a library designed to build automated conversation flows. Key features include:

• Provider-agnostic WhatsApp conversation flows.
• Automated responses for frequently asked questions.
• Automatic message receiving and responding.
• Customer interaction tracking.
• Extensible functionality via triggers.

The @builderbot/provider-voice-whatsapp provider uses a specialized architecture to handle voice calls via the Meta Graph API. It manages real-time audio using RTCPeerConnection and processes audio streams through several components:

• MetaCallClient: Manages call lifecycle (pre_accept, accept, end) via Graph API.
• Audio Processing: Uses RTCAudioSink to receive inbound Opus frames as PCM and RTCAudioSource to push TTS PCM back to the caller.
• Speech Processing: Employs a SilenceSegmenter for utterance boundaries, an ISttAdapter (defaulting to OpenAI Whisper) for Speech-to-Text, and an ITtsAdapter (defaulting to OpenAI TTS) for Text-to-Speech.
• Webhook Server: A polka HTTP server handles Meta hub verification (GET /webhook) and inbound call events (POST /webhook).

To start a new BuilderBot project, use the create-builderbot CLI tool. This will scaffold a new project allowing you to build automated conversation flows that are agnostic to the WhatsApp provider, set up automated FAQ responses, and manage customer interactions.

npm create builderbot@latest

When calling createBot, you can disable provider notices (inbound messages and delivery status updates) by setting logs.notices to false in the bot configuration object.

const { httpServer } = await createBot(
    { flow, provider: adapterProvider, database },
    {
        logs: {
            notices: false,
        },
    }
)

Initialize the GupshupProvider using createProvider from @builderbot/bot. You must provide an apiKey, srcName, and phoneNumber. You can also configure detailed logging for inbound messages, status updates, and outbound errors.

import { createProvider } from '@builderbot/bot'
import { GupshupProvider } from '@builderbot/provider-gupshup'

const adapterProvider = createProvider(GupshupProvider, {
    apiKey: 'YOUR_API_KEY',
    srcName: 'YOUR_APP_NAME',
    phoneNumber: 'YOUR_SOURCE_NUMBER',
    logs: {
        inbound: false,
        status: 'failed',
        outboundErrors: true,
        rawOnFailed: false,
    },
})

To set up the base-ts-tiktok-memory example, you must first build the TikTok provider from the monorepo root and then install dependencies within the starter application directory. This starter is designed for polling TikTok videos and replying publicly to comments.

# From the monorepo root, build the provider
pnpm --filter @builderbot/provider-tiktok build

# Navigate to the starter and install dependencies
cd starters/apps/base-ts-tiktok-memory
pnpm install

Install the multi-tenant bot manager using pnpm.

pnpm add @builderbot/manager

To receive events, configure your Facebook App dashboard:

1. Navigate to Instagram > Settings.
2. Add your webhook URL (e.g., https://your-domain.com/webhook).
3. Enter your verifyToken.
4. Subscribe to the following events:
   • messages
   • messaging_postbacks
   • comments (required if you want to listen to post comments)

Set your Redirect URI in the GHL Marketplace to point to your server's OAuth callback endpoint.

Examples:

• Production: https://your-domain.com/oauth/callback
• Local development: http://localhost:3000/oauth/callback

Webhook Setup:

1. Use your server's webhook URL (e.g., https://your-domain.com/webhook). For local testing, use an ngrok URL.
2. In GHL, go to Settings > Integrations > Webhooks and add a webhook.
3. Required Event: InboundMessage (requires conversations/message.readonly scope) to receive incoming messages.
4. Recommended Events: OutboundMessage and ConversationUnreadUpdate.