NuClaw Channel Adapters

Channel adapters for the NuClaw AI agent platform. Each adapter provides a consistent interface for fetching and sending messages across different communication platforms.

Adapters

Adapter	Description	API	Auth
GitHub	Issues, PRs, comments, webhooks	REST API	Bearer token + HMAC webhook
WhatsApp	Cloud API messaging, media, interactive	Graph API v21.0	Bearer token + webhook verify
Teams	Bot Framework messaging, cards	REST API v3	OAuth2 client credentials
Linear	Issue tracking, state transitions	GraphQL API	API key (Bearer)

Installation

go get ./...

Usage

import "nuclaw/pkg/channels"

// GitHub
ghAdapter, _ := channels.NewGitHubAdapter(cfg)
msgs, err := ghAdapter.FetchMessages(ctx)
ghAdapter.StartPolling(ctx, handler, 30*time.Second)

// Incoming webhooks
msg, err := ghAdapter.HandleWebhook(payload, signatureHeader)

// Outgoing messages
ghAdapter.SendMessage(ctx, "123", &channels.OutgoingMessage{Content: "hello"})

// WhatsApp
waAdapter, _ := channels.NewWhatsAppAdapter(cfg)
msgs, _ := waAdapter.ProcessWebhook(payload)
challenge, err := waAdapter.VerifyWebhook(mode, token, challenge)

// Teams
teamsAdapter, _ := channels.NewTeamsAdapter(cfg)
teamsAdapter.SendCard(ctx, convID, "Title", "text", buttons)

// Linear
linearAdapter, _ := channels.NewLinearAdapter(cfg)
linearAdapter.SetTeamID("team-abc")
linearAdapter.TransitionIssue(ctx, issueID, stateID)

Configuration

Each adapter requires specific environment variables:

GitHub

Variable	Required	Description
GITHUB_OWNER	Yes	Repository owner (user or org)
GITHUB_REPO	Yes	Repository name
GITHUB_TOKEN	Yes	Personal access token with repo scope
GITHUB_WEBHOOK_SECRET	For webhooks	Secret configured in GitHub webhook settings

WhatsApp

Variable	Required	Description
WHATSAPP_PHONE_NUM_ID	Yes	Phone number ID from WhatsApp Business
WHATSAPP_ACCESS_TOKEN	Yes	Cloud API permanent access token
WHATSAPP_VERIFY_TOKEN	For webhooks	Token used for webhook subscription verification

Microsoft Teams

Variable	Required	Description
MS_TEAMS_APP_ID	Yes	Bot application (client) ID
MS_TEAMS_APP_SECRET	Yes	Bot client secret for OAuth2
MS_TEAMS_TENANT_ID	No	Tenant ID (defaults to botframework.com for multi-tenant)

Linear

Variable	Required	Description
LINEAR_API_KEY	Yes	API key from Linear settings
LINEAR_TEAM_ID	No	Default team ID for issue creation (set via SetTeamID())

Resilience

All adapters include production-grade HTTP resilience:

• Exponential backoff with jitter — Retries on 429 (rate limit), 5xx server errors (up to 3 attempts, 500ms initial backoff, 30s cap). Respects Retry-After headers.
• Rate limit awareness — Parses standard rate limit headers (X-RateLimit-*, RateLimit-*) and logs warnings when approaching exhaustion.
• Structured logging — Uses log/slog with channel-scoped attributes for all errors and warnings.

Development

# Build
go build ./...

# Test
go test ./...

# Vet
go vet ./...

License

MIT License

---

Created by Chris Bunting for NuClaw