Pingring Slack Bot

A Slack bot that allows users to send voice messages to other users via phone calls using Vonage APIs.

Features

• Voice Message Delivery: Send voice messages to Slack users via phone calls
• Slack Connect Support: Works in Slack Connect channels
• Event Tracking: Logs all requests with unique event IDs
• Delivery Status: Receives webhooks about call delivery status
• Thread Support: All responses are posted in threads to keep channels clean
• SQLite Database: Lightweight, file-based database for easy deployment

Usage

In any Slack channel where the bot is installed:

@pingring @username Hey, this is an urgent message!

The bot will:

1. Look up the phone number of the mentioned user
2. Make a call via Vonage APIs
3. Play the transcribed message
4. Log the event and provide status updates in the thread

Setup

Prerequisites

• Go 1.21+
• Slack App with Bot Token
• Vonage API credentials with a phone number

Environment Variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Installation

1. Clone the repository
2. Install dependencies: go mod download
3. Set up environment variables
4. Run the application: go run cmd/pingring/main.go

Quick Start

# Setup development environment
make setup

# Edit .env with your credentials
vim .env

# Run the application
make run

Docker Deployment

# Create data directory for SQLite database
mkdir -p data

# Copy environment file
cp .env.example .env
# Edit .env with your credentials

# Start the service
make docker-run

Slack App Configuration

1. Create a new Slack app at https://api.slack.com/apps
2. Enable Bot Token Scopes:
   • app_mentions:read
   • chat:write
   • users:read
3. Subscribe to Bot Events:
   • app_mention
4. Set Event Request URL to: https://your-domain.com/slack/events
5. Install the app to your workspace

Vonage Configuration

1. Create a Vonage application at https://dashboard.nexmo.com/
2. Configure webhook endpoint: https://your-domain.com/vonage/webhook
3. Purchase a phone number for outbound calls
4. Set up JWT authentication with your private key

Important: The Vonage JWT implementation is simplified in this code. In production, you must:

1. Generate a private key for your Vonage application
2. Store it securely
3. Implement proper JWT signing in the generateJWT() method

API Endpoints

• POST /slack/events - Slack event webhook
• POST /slack/interactive - Slack interactive components
• POST /vonage/webhook - Vonage delivery status webhook
• GET /health - Health check endpoint

Database Schema

The bot uses SQLite with the following schema:

CREATE TABLE events (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    slack_org_id TEXT NOT NULL,
    message TEXT NOT NULL,
    thread_id TEXT,
    channel_id TEXT NOT NULL,
    phone_number TEXT NOT NULL,
    vonage_call_id TEXT,
    status TEXT NOT NULL DEFAULT 'pending',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Architecture

The application follows a clean architecture pattern:

cmd/
├── pingring/           # Application entry point
internal/
├── config/            # Configuration management
├── db/                # Database connection and migrations
├── handlers/          # HTTP handlers for Slack and Vonage
├── models/            # Data models
├── repository/        # Data access layer
├── services/          # Business logic
├── slack/             # Slack API client
└── vonage/            # Vonage API client

Thread Support

All bot responses are posted in threads to keep channels clean:

• Initial responses create a new thread from the mention message
• Status updates are posted to the same thread
• Error messages are also posted in threads

Security Considerations

• Request signature verification for Slack webhooks
• Environment variable management for sensitive data
• SQLite database with proper file permissions
• JWT token generation for Vonage API (needs proper implementation)

Monitoring and Logging

The bot includes comprehensive logging for:

• Incoming Slack events
• Vonage API calls
• Database operations
• Error tracking

Development

Available Make Commands

make help          # Show all available commands
make setup         # Setup development environment
make run           # Run the application
make build         # Build the application
make test          # Run tests
make docker-build  # Build Docker image
make docker-run    # Run with Docker Compose
make logs          # View application logs
make fmt           # Format code
make lint          # Lint code
make clean         # Clean build artifacts

Testing

Run tests with:

make test

Code Formatting

Format code with:

make fmt

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Run make fmt and make lint
6. Submit a pull request

License

MIT License

Support

For questions or issues, please open an issue on GitHub.