botbook/src/18-appendix-external-services/channels.md

Channel Integrations

This guide covers integrating messaging channels with General Bots, focusing on WhatsApp Business API integration using Twilio-purchased phone numbers.

Overview

General Bots supports multiple messaging channels through a unified API. This section focuses on WhatsApp Business API, the most widely used business messaging platform globally.

Supported Channels

Channel	Status	Config Keys
WhatsApp	✅ Production Ready	whatsapp-api-key, whatsapp-phone-number-id
Twilio SMS	✅ Production Ready	twilio-account-sid, twilio-auth-token
Instagram	✅ Production Ready	instagram-access-token, instagram-page-id
Microsoft Teams	✅ Production Ready	teams-app-id, teams-app-password

WhatsApp Business Integration

The most popular channel for business messaging. Complete integration guide: WhatsApp Quick Start

Quick Setup (5 minutes)

1. Purchase a phone number from Twilio

   # Twilio Console > Phone Numbers > Buy a Number
   # Select: Voice capability (required for verification)
   # Example: +553322980098
   

2. Create Meta App with WhatsApp

   # https://developers.facebook.com/apps/
   # Create App > Business > Add WhatsApp product
   

3. Configure credentials in config.csv

   whatsapp-enabled,true
   whatsapp-api-key,EAAQdlso6aM8BOwlhc3yM6bbJkGyibQPGJd87zFDHtfaFoJDJPohMl2c5nXs4yYuuHwoXJWx0rQKo0VXgTwThPYzqLEZArOZBhCWPBUpq7YlkEJXFAgB6ZAb3eoUzZAMgNZCZA1sg11rT2G8e1ZAgzpRVRffU4jmMChc7ybcyIwbtGOPKZAXKcNoMRfUwssoLhDWr
   whatsapp-phone-number-id,1158433381968079
   whatsapp-business-account-id,390727550789228
   whatsapp-webhook-verify-token,4qIogZadggQ.BEoMeciXIdl_MlkV_1DTx8Z_i0bYPxtSJwKSbH0FKlY
   whatsapp-application-id,323250907549153
   

BASIC Keywords for WhatsApp

REM Send a message
SEND WHATSAPP TO "+5511999999999" WITH "Hello from General Bots!"

REM Handle incoming messages
ON WHATSAPP MESSAGE RECEIVED
  LET SENDER$ = GET WHATSAPP SENDER NUMBER
  LET MESSAGE$ = GET WHATSAPP MESSAGE BODY
  
  REM Echo message back
  SEND WHATSAPP TO SENDER$ WITH "You said: " + MESSAGE$
END ON

Credential Reference

Credential	Format	Example	Purpose
Access Token	EAAQ...	EAAQdlso6aM8BOwl...	API authentication
Phone Number ID	16 digits	1158433381968079	Message sending endpoint
WABA ID	15 digits	390727550789228	Business account identifier
Verify Token	Custom string	4qIogZadggQ.BEoMeci...	Webhook security
Application ID	15 digits	323250907549153	App identifier

Phone Number Verification

Twilio numbers require voice call verification (not SMS):

1. Configure Twilio webhook to capture verification calls

   <!-- TwiML for voice handling -->
   <?xml version="1.0" encoding="UTF-8"?>
   <Response>
     <Gather action="https://twimlets.com/voicemail?Email=your@email.com">
       <Say voice="alice">Please enter your verification code.</Say>
     </Gather>
   </Response>
   

2. In Meta Business Suite: Select "Phone Call" verification method

3. Enter the 6-digit code received via email

4. Verification complete - number ready for WhatsApp

See: Webhook Configuration Guide

Advanced Configuration

Message Templates

For business-initiated messages outside the 24-hour window:

// Send template message
POST https://graph.facebook.com/v18.0/1158433381968079/messages
{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "pt_BR" }
  }
}

Rate Limiting

WhatsApp enforces rate limits per tier:

Tier	Messages/Day	Messages/Second
Tier 1	1,000	1
Tier 2	10,000	5
Tier 3	100,000	50
Tier 4	Unlimited	1,000

Implement rate limiting in your bot:

REM Simple rate limiting
LET LAST_SENT = 0
SUB SEND WHATSAPP WITH LIMIT TO NUMBER$, MESSAGE$
  LET NOW = TIMER
  IF NOW - LAST_SENT < 1 THEN
    WAIT 1 - (NOW - LAST_SENT)
  END IF
  SEND WHATSAPP TO NUMBER$ WITH MESSAGE$
  LAST_SENT = TIMER
END SUB

Webhook Security

Always verify webhook signatures:

// Node.js signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, appSecret) {
  const expected = 'sha256=' + 
    crypto.createHmac('sha256', appSecret)
      .update(payload)
      .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Complete Documentation

For detailed guides and examples:

• WhatsApp Quick Start Guide - 30-minute setup walkthrough
• Webhook Configuration - Detailed webhook setup for Twilio and Meta
• Code Examples - Examples in BASIC, Node.js, and Python
• Troubleshooting Guide - Common issues and solutions
• Quick Reference - Commands, configs, and snippets

Other Channels

Twilio SMS

Simple SMS integration using Twilio:

# config.csv
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,your_auth_token_here
twilio-from-number,+15551234567

REM Send SMS
SEND SMS TO "+5511999999999" WITH "Hello via SMS!"

Instagram Direct Messages

Connect Instagram messaging:

# config.csv
instagram-access-token,EAAxxxx...
instagram-page-id,123456789012345

REM Send Instagram DM
SEND INSTAGRAM TO "1234567890" WITH "Hello via Instagram!"

Configuration Template

Complete channel configuration example:

# config.csv

# WhatsApp Business (Primary channel)
whatsapp-enabled,true
whatsapp-api-key,EAAQdlso6aM8BOwlhc3yM6bbJkGyibQPGJd87zFDHtfaFoJDJPohMl2c5nXs4yYuuHwoXJWx0rQKo0VXgTwThPYzqLEZArOZBhCWPBUpq7YlkEJXFAgB6ZAb3eoUzZAMgNZCZA1sg11rT2G8e1ZAgzpRVRffU4jmMChc7ybcyIwbtGOPKZAXKcNoMRfUwssoLhDWr
whatsapp-phone-number-id,1158433381968079
whatsapp-business-account-id,390727550789228
whatsapp-webhook-verify-token,4qIogZadggQ.BEoMeciXIdl_MlkV_1DTx8Z_i0bYPxtSJwKSbH0FKlY

# Twilio SMS (Backup channel)
twilio-enabled,false
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,your_auth_token_here
twilio-from-number,+15551234567

# Instagram (Social channel)
instagram-enabled,false
instagram-access-token,EAAxxxx...
instagram-page-id,123456789012345

Troubleshooting

Common Issues

Issue: Phone number verification fails

• Solution: Ensure "Phone Call" verification is selected (not SMS)
• Solution: Verify Twilio webhook is configured correctly
• See: Troubleshooting Guide

Issue: Messages not sending

• Solution: Check access token validity
• Solution: Verify phone number format: 5511999999999 (no +, no spaces)
• Solution: Ensure webhook is subscribed to "messages" field

Issue: Rate limit errors

• Solution: Implement rate limiting in your bot
• Solution: Use message queues for bulk sending
• See: Code Examples

Best Practices

1. Never hardcode credentials - Always use config.csv
2. Implement retry logic - Handle API failures gracefully
3. Monitor rate limits - Respect platform limits
4. Secure webhooks - Verify all incoming requests
5. Test thoroughly - Use ngrok for local testing
6. Log everything - Track message delivery and errors
7. Use templates - Pre-approved templates for business-initiated messages
8. Handle errors - Provide user-friendly error messages

Support

• Documentation: Full guide
• Examples: Code samples
• Community: General Bots Discord
• Meta Docs: WhatsApp Business API
• Twilio Docs: Twilio WhatsApp

Next Steps

1. Complete the Quick Start Guide
2. Set up webhooks using Webhook Configuration
3. Explore Code Examples for your use case
4. Configure monitoring and error handling
5. Test with your team before launching to users

For configuration of other services (LLM providers, databases, etc.), see Appendix B: External Services.