Channel Setup

Messaging Channel Setup

Connect Commerce Index to Telegram, WhatsApp Business, Slack, or iMessage. Once linked, you can manage your store, run commands, and receive alerts from any messaging platform.

Telegram is the fastest way to get started with CI messaging. Create a bot, connect it to your CI account, and start issuing commands in under 5 minutes.

Create a Bot via @BotFather

Open Telegram, search for @BotFather, and send the /newbot command. Choose a name and username for your bot.

# Conversation with @BotFather
You: /newbot
BotFather: Alright, a new bot. How are we going to call it?
You: My Store CI Bot
BotFather: Good. Now let's choose a username.
You: mystoreci_bot
BotFather: Done! Congratulations on your new bot.
         Use this token to access the HTTP API:
         7123456789:AAHk8mN2xR_vB3cDeFgHiJkLmNoPqRsTuVw
         Keep your token secure and store it safely.

Configure Webhook URL

# Set the webhook URL for your bot
curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.commerceindex.com/v1/webhooks/telegram",
    "secret_token": "your_ci_webhook_secret",
    "allowed_updates": ["message", "callback_query"]
  }'

# Expected response
{
  "ok": true,
  "result": true,
  "description": "Webhook was set"
}

Set Bot Commands

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands": [
    {"command": "pulse", "description": "Quick health check"},
    {"command": "brief", "description": "Daily business summary"},
    {"command": "deals", "description": "List and manage deals"},
    {"command": "inventory", "description": "Check stock levels"},
    {"command": "agents", "description": "View active agents"},
    {"command": "inbox", "description": "Pending approvals"},
    {"command": "help", "description": "Show all commands"}
  ]}'

Add Token in CI Settings

Go to Settings > Channels > Telegram in your CI dashboard. Paste your bot token and webhook secret. Click Connect. Send /help to your bot to verify the connection.

WhatsApp Business

WhatsApp Business integration uses the Meta Cloud API. You need a Meta Business account and a verified phone number dedicated to your CI bot.

Create a Meta Business Account

Go to business.facebook.com and create a business account. Navigate to Meta for Developers, create a new app, and add the WhatsApp product.

Register a Phone Number

Add a phone number to your WhatsApp Business Account. This number must not be registered with any personal WhatsApp account. Meta verifies it via SMS or voice call.

Configure Webhook Verification

Meta requires webhook verification via a GET challenge. CI handles this automatically.

# Webhook configuration in Meta Developer Portal:
Callback URL:    https://api.commerceindex.com/v1/webhooks/whatsapp
Verify Token:    your_ci_whatsapp_verify_token

# Subscribed webhook fields:
- messages              # Incoming messages from users
- message_deliveries    # Delivery status updates
- message_reads         # Read receipt notifications

# Meta sends a GET request to verify:
# GET /webhooks/whatsapp?hub.mode=subscribe
#     &hub.verify_token=YOUR_VERIFY_TOKEN
#     &hub.challenge=CHALLENGE_STRING
# CI responds with the challenge string if token matches

Set Up Message Templates

WhatsApp requires pre-approved templates for business-initiated messages (daily briefs, alerts).

# Required message templates for CI

Template: ci_daily_brief
Category: UTILITY
Body: "{{1}} Daily Brief for {{2}}
Revenue: {{3}} | Orders: {{4}} | Health Score: {{5}}
View full report: {{6}}"

Template: ci_alert
Category: UTILITY
Body: "Alert: {{1}}
{{2}}
Action required: {{3}}"

Template: ci_approval_request
Category: UTILITY
Body: "Approval needed: {{1}}
Agent: {{2}} | Confidence: {{3}}
Details: {{4}}
Reply APPROVE or REJECT"

Add Credentials in CI Settings

Go to Settings > Channels > WhatsApp. Enter your Phone Number ID, WhatsApp Business Account ID, permanent access token, and verify token. Click Connect.

Slack

Slack integration enables CI commands via slash commands, approval workflows in channels, and automated notifications. Ideal for teams that already live in Slack.

Create a Slack App

Go to api.slack.com/apps, click "Create New App", choose "From scratch", and add these OAuth scopes:

# Required OAuth Scopes (Bot Token Scopes)
chat:write        # Send messages to channels
commands          # Register and respond to slash commands
users:read        # Read user profile info for account linking
files:write       # Upload reports and charts
reactions:read    # Track approval reactions
im:history        # Read DM history for command context
im:write          # Send DMs for private notifications

Install to Your Workspace

Go to OAuth & Permissions, add the scopes above, then click Install to Workspace. Copy the Bot User OAuth Token.

Configure Slash Commands

In Slash Commands, create a single command that routes all CI commands through one endpoint.

# Slash Command Configuration
Command:           /ci
Request URL:       https://api.commerceindex.com/v1/webhooks/slack/command
Short Description: Commerce Index commands
Usage Hint:        [pulse | brief | deals | inventory | agents | help]

# Example usage in Slack:
/ci pulse          # Quick health check
/ci brief          # Daily summary
/ci deals          # List active deals
/ci inventory      # Stock level overview

Connect in CI Settings

Go to Settings > Channels > Slack. Enter your Bot Token, Signing Secret, and default channel. Click Connect. Test with /ci help in any channel.

iMessage

Beta. Apple provides no public iMessage API, so iMessage connects through a relay — a Mac signed into Messages.app, or a hosted iMessage vendor. iMessage runs over data: every message is free; the relay itself is the only cost. Until a relay is deployed, iPhone users can simply text our number — iMessage falls back to SMS automatically and a single text signs you up.

How the relay contract works

Commerce Index is relay-agnostic. Any relay that speaks this contract works — inbound messages POST to our webhook; outbound replies POST to the relay:

# Inbound (relay → Commerce Index)
POST https://<api-host>/api/v2/messaging/webhooks/imessage
X-Relay-Secret: <IMESSAGE_RELAY_SECRET>
{"from": "+15551234567", "text": "START"}

# Outbound (Commerce Index → relay)
POST <IMESSAGE_RELAY_URL>/send
Authorization: Bearer <IMESSAGE_RELAY_SECRET>
{"to": "+15551234567", "text": "Welcome to Commerce Index..."}

# Backend env vars
IMESSAGE_RELAY_URL=https://your-relay.example.com
IMESSAGE_RELAY_SECRET=<shared secret>

Option A — Mac relay (reference implementation)

A Mac (mini recommended, M1+) signed into Messages.app with a dedicated Apple ID. The reference bridge in openclaw/skills/ci-platforms/imessage.ts sends via AppleScript and polls ~/Library/Messages/chat.db (requires Full Disk Access in System Settings > Privacy & Security). Wrap it with the relay contract above and expose it to the backend (a Cloudflare Tunnel works well behind NAT). Cost: the Mac itself.

Option B — Hosted iMessage vendor

Hosted iMessage API vendors run the Macs for you and can adapt to the same relay contract. Be aware these services operate in a gray area of Apple's terms and can experience disruptions — treat iMessage as an enhancement, with WhatsApp/SMS as the dependable primary channels.

What works once connected

Inbound-first signup (a first iMessage from an unknown number provisions the account, exactly like WhatsApp), the full conversational assistant, all commands, and Apple-ID email handles linked to existing accounts by email match. Every message is free — iMessage is data-based.

Platform Comparison

Feature	Telegram	WhatsApp	Slack	iMessage
Setup	Easy	Medium	Medium	Advanced
All Commands	Yes	Yes	Yes	Yes
Inline Buttons	Yes	No	Yes	No
Hardware	None	None	None	Mac Mini
Cost	Free	Meta fees	Free	Mac cost