Configuring Connectors

Connectors are communication channels used to send notifications and OTPs to you and your survivors. This guide covers setting up each connector type.

Adding your own connectors (Pro or self-hosted)? See the detailed User connectors guide for step-by-step setup and links to Twilio, Meta, and more.

Overview

BAP supports four connector types:

You should configure at least two connectors for redundancy.

Adding a Connector

Step 1: Navigate to Connectors

1. Log into the Host Dashboard
2. Go to Settings → Connectors
3. Click "Add Connector"

Step 2: Choose Connector Type

Select the type you want to add:

• Email (SMTP)
• SMS (Twilio)
• WhatsApp (Meta Cloud API)
• Telegram

Step 3: Configure Credentials

Each connector type has different required fields (see below).

Step 4: Test and Save

1. Click "Test Connector"
2. Enter a test destination (your email/phone)
3. Click "Send Test"
4. If successful, click "Save Connector"

Email (SMTP)

Email via SMTP is the most common connector. Works with any SMTP provider (SendGrid, Resend, Postmark, Mailgun, or your own SMTP server).

Prerequisites

• An SMTP provider account or your own mail server
• Verified sender email address or domain
• SMTP credentials (host, port, username, password)

Configuration Fields

Setup Steps

1. Choose an SMTP provider:

   • SendGrid — free tier available
   • Resend — developer-friendly
   • Postmark — high deliverability
   • Mailgun — free tier available
   • Or any SMTP server you control

2. Get SMTP credentials:

   • Create an API key or SMTP credentials in your provider's dashboard
   • Note the SMTP host, port, username, and password

3. Verify sender:

   • Verify your sending domain or email address with your provider
   • For production, set up SPF, DKIM, and DMARC records

Testing

Click "Send Test" and enter your email address. You should receive a test message.

Costs

Varies by provider:

• SendGrid: 100 emails/day free
• Resend: 3,000 emails/month free
• Postmark: 100 emails/month free

SMS (Twilio)

Twilio provides SMS delivery worldwide. BAP uses Twilio API Key (Key SID + Secret), not Account SID + Auth Token, for better security and key rotation.

Prerequisites

• Twilio account
• Twilio phone number (for sending)
• API Key created in Twilio Console (Key SID starts with SK...)

Configuration Fields

Twilio Setup Steps

1. Create Account:

   • Sign up at twilio.com
   • Verify your phone number

2. Get Phone Number:

   • Go to Phone Numbers → Buy a Number
   • Note the phone number (format: +1...)

3. Create API Key:

   • Go to Twilio Console → API keys
   • Create a new API Key; note the Key SID (SK...) and Secret (shown once)

4. Enter in BAP:

   • API Key SID, API Key Secret, From Number

Testing

Click "Send Test" and enter a phone number. You should receive an SMS.

Costs

Twilio pricing:

• ~$0.007-0.08 per SMS (varies by country)
• $1/month per phone number

WhatsApp (Meta Cloud API)

WhatsApp provides reliable delivery with rich formatting.

Prerequisites

• Meta Business account
• WhatsApp Business API enabled
• Business phone number

Configuration Fields

Meta Setup Steps

1. Create Meta App:

   • Go to developers.facebook.com
   • Create new app (type: Business)
   • Add WhatsApp product

2. Configure WhatsApp:

   • Go to WhatsApp → API Setup
   • Note Phone Number ID
   • Note Business Account ID

3. Get Access Token:

   • Go to Settings → Advanced → Access Tokens
   • Generate temporary or permanent token

4. Verify Webhook:

   • Set up webhook for testing (optional)

Testing

Click "Send Test" and enter a WhatsApp number. You should receive a message.

Costs

Meta Cloud API pricing:

• Conversations: ~$0.015-0.40 per conversation
• Free tier available for testing

Telegram

Telegram provides fast delivery with no phone number required.

Prerequisites

• Telegram account
• Create a bot via @BotFather

Configuration Fields

Telegram Setup Steps

1. Create Bot:

   • Open Telegram
   • Search for @BotFather
   • Send /newbot
   • Follow prompts to name your bot
   • Note the bot token

2. Get Token:

   • BotFather shows token after creation
   • Format: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

3. Test Bot:

   • Open conversation with your bot
   • Send /start
   • This "wakes up" the bot

Testing

Click "Send Test" and enter your Telegram username or start a chat with the bot first.

Costs

Telegram Bot API is free.

Managing Connectors

Viewing Connectors

The Connectors page shows all configured connectors:

Editing Connectors

1. Click on a connector
2. Modify fields
3. Click "Save Changes"

Testing Individual Connectors

1. Click "Test" next to connector
2. Enter destination
3. View result

Deleting Connectors

1. Click "Delete" on connector
2. Confirm deletion

Constraint: If it's your only connector and you have an active will, you must add another first.

Reordering Priority

Drag and drop connectors to change priority order. The system tries connectors in order during:

• Liveness check escalation
• OTP delivery to survivors

Connector Fallback

How Fallback Works

When sending a notification or OTP:

1. Try primary connector
2. If fails, try next in priority
3. Continue until successful or all fail

Fallback Examples

Example 1: Email → SMS → Telegram

OTP request for Jane
→ Try Email: Success → Delivered

Example 2: Email → SMS → Telegram

OTP request for Jane
→ Try Email: Failed (invalid email)
→ Try SMS: Success → Delivered

Configuring Fallback

For each survivor, set their connector priority order:

["email", "sms", "whatsapp", "telegram"]

For liveness checks, the system uses your configured connectors in priority order.

Best Practices

Redundancy

• Configure at least 2 connectors
• Use different delivery mechanisms (e.g., email + SMS)
• Test connectors periodically

For International Survivors

• WhatsApp — Best for international (lower cost, reliable)
• Telegram — Good alternative
• SMS — Can be expensive internationally

Cost Management

• Email is cheapest for most use cases
• SMS costs vary by country
• WhatsApp/Telegram are often cheaper than SMS internationally

Regular Testing

• Test connectors monthly
• Update credentials before expiration
• Monitor delivery success rates

Troubleshooting

"Connection failed"

Check credentials carefully:

• SMTP host/port are correct
• Tokens haven't expired
• Phone numbers are verified

"Rate limited"

Some providers rate limit. Wait and try again, or use a different provider.

"Invalid credentials"

• Re-verify credentials in provider console
• Check SMTP port (usually 587 for TLS, 465 for SSL)
• Ensure account is active

"Sender not verified"

• Complete provider verification
• Verify your sending domain with SPF/DKIM records

Messages not delivering

1. Check provider status
2. Verify recipient exists
3. Check spam/junk folders
4. Review provider logs

API Reference

Connectors can also be managed via API:

GET    /api/connectors           - List connectors
POST   /api/connectors          - Create connector
PUT    /api/connectors/:id      - Update connector
DELETE /api/connectors/:id      - Delete connector
POST   /api/connectors/:id/test - Test connector

See API Reference - Connectors for details.

Next Steps

• Connecting Storage — Set up storage backends
• Liveness Settings — Configure check intervals
• Quickstart Guide — Initial setup flow