Gateways

Gateways connect your agent to external communication channels.

Overview

Supported channels:

Email - SMTP/IMAP integration
Telegram - Bot API
WhatsApp - Business API
Slack - Workspace integration
Discord - Bot integration
X.com (Twitter) - Post tweets and interactions
SMS - Twilio/providers
Webhook - Custom HTTP endpoints

Cross-Gateway Features

When the same contact uses multiple gateways, they share:

Memory - Preferences and facts persist across channels
History - Search conversations across all platforms
Context - Agent knows who they're talking to regardless of channel

See Contacts - Cross-Gateway Memory for details.

Gateway Types

Email

json

{
  "type": "email",
  "name": "Support Email",
  "config": {
    "smtp_host": "smtp.example.com",
    "smtp_port": 587,
    "smtp_user": "[email protected]",
    "smtp_password": "{{secrets.smtp_password}}",
    "from_name": "Support Team",
    "from_email": "[email protected]"
  }
}

json

{
  "type": "telegram",
  "name": "Support Bot",
  "config": {
    "bot_token": "{{secrets.telegram_token}}",
    "webhook_url": "https://your-domain.com/webhooks/telegram"
  }
}

json

{
  "type": "whatsapp",
  "name": "WhatsApp Business",
  "config": {
    "phone_number_id": "123456789",
    "access_token": "{{secrets.whatsapp_token}}",
    "business_id": "987654321"
  }
}

Slack

json

{
  "type": "slack",
  "name": "Workspace",
  "config": {
    "bot_token": "{{secrets.slack_token}}",
    "app_id": "A123456",
    "signing_secret": "{{secrets.slack_signing}}"
  }
}

Discord

json

{
  "type": "discord",
  "name": "Server Bot",
  "config": {
    "bot_token": "{{secrets.discord_token}}",
    "application_id": "123456789"
  }
}

X.com (Twitter)

json

{
  "type": "x",
  "name": "Twitter Bot",
  "config": {
    "api_key": "{{secrets.x_api_key}}",
    "api_secret": "{{secrets.x_api_secret}}",
    "access_token": "{{secrets.x_access_token}}",
    "access_token_secret": "{{secrets.x_access_token_secret}}"
  }
}

X.com Features

Feature	Description
Post tweets	Send tweets from your agent
Reply to mentions	Respond to @mentions
Direct messages	Send and receive DMs
Media upload	Attach images to tweets

Posting a Tweet

bash

curl -X POST https://your-domain.com/api/agents/{id}/messages \
  -d '{
    "gateway_id": "x-gateway-123",
    "content": "Hello from my AI agent! 🤖",
    "options": {
      "media_url": "https://example.com/image.png"
    }
  }'

SMS

json

{
  "type": "sms",
  "name": "Twilio SMS",
  "config": {
    "provider": "twilio",
    "account_sid": "ACxxxx",
    "auth_token": "{{secrets.twilio_token}}",
    "from_number": "+1234567890"
  }
}

Webhook

json

{
  "type": "webhook",
  "name": "Custom Integration",
  "config": {
    "url": "https://api.example.com/messages",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{secrets.api_key}}"
    }
  }
}

Creating Gateways

Via Dashboard

Navigate to Services
Click Add Gateway
Select type
Configure credentials
Test connection
Save

Via API

bash

curl -X POST https://your-domain.com/api/agents/{id}/gateways \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "name": "Support Bot",
    "config": {
      "bot_token": "123456:ABC..."
    }
  }'

Managing Gateways

List Gateways

bash

curl https://your-domain.com/api/agents/{id}/gateways

Get Gateway

bash

curl https://your-domain.com/api/agents/{id}/gateways/{gatewayId}

Update Gateway

bash

curl -X PUT https://your-domain.com/api/agents/{id}/gateways/{gatewayId} \
  -d '{
    "config": {
      "from_name": "New Name"
    }
  }'

Delete Gateway

bash

curl -X DELETE https://your-domain.com/api/agents/{id}/gateways/{gatewayId}

Sending Messages

Via API

bash

curl -X POST https://your-domain.com/api/agents/{id}/messages \
  -d '{
    "gateway_id": "gateway-123",
    "to": "+1234567890",
    "content": "Hello from the agent!"
  }'

Via Workflow

json

{
  "type": "send-message",
  "data": {
    "gateway": "telegram-bot",
    "to": "{{contact.telegram}}",
    "message": "Your order is ready!"
  }
}

Receiving Messages

Webhook Processing

External Service
     │
     │ Webhook POST
     ▼
┌─────────────────┐
│   Gateway       │
│   Webhook       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Message       │
│   Processing    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Agent         │
│   Response      │
└─────────────────┘

Message Format

json

{
  "id": "msg-123",
  "gateway_id": "gateway-456",
  "direction": "inbound",
  "from": "+1234567890",
  "to": "agent",
  "content": "Hello!",
  "metadata": {
    "channel": "sms",
    "timestamp": "2024-12-15T10:00:00Z"
  }
}

Default Gateway

Set a default gateway per channel:

json

{
  "type": "telegram",
  "is_default": true
}

Gateway Status

Status	Description
`active`	Ready to send/receive
`inactive`	Disabled
`error`	Configuration issue
`rate_limited`	Temporarily limited

Integration

With Contacts

Route based on contact preference:

json

{
  "type": "send-message",
  "data": {
    "contact_id": "{{contact.id}}",
    "channel": "{{contact.preferred_channel}}",
    "message": "Hello {{contact.name}}!"
  }
}

With Conversations

Messages are grouped by conversation:

json

{
  "conversation_id": "conv-123",
  "gateway_id": "gateway-456",
  "contact_id": "contact-789"
}

Best Practices

1. Secure Credentials

Store sensitive data securely:

Use secrets storage
Never log tokens
Rotate regularly

2. Test Before Deploy

Verify configuration:

Send test messages
Check webhook delivery
Monitor responses

3. Handle Rate Limits

Respect provider limits:

Implement backoff
Queue messages
Monitor usage

4. Log Messages

Track all communication:

Store message history
Log delivery status
Audit access

5. Use Templates

Standardize messages:

Create message templates
Use variables
Maintain consistency

Troubleshooting

Messages Not Sending

Verify credentials
Check gateway status
Review error logs
Test with simple message

Webhooks Not Received

Verify webhook URL
Check authentication
Review server logs
Test with curl

Rate Limiting

Reduce message frequency
Implement queuing
Contact provider
Use multiple gateways

Processing Architecture

The gateway system uses a modular processor architecture that handles:

Input Parsing - Platform-specific webhook parsing into standardized format
Contact Resolution - Address book lookup/creation
Conversation Management - Thread tracking across platforms
Output Formatting - Platform-specific message formatting (HTML, Block Kit, etc.)
Delivery - Platform API integration with rate limiting

Webhook → Parser → Contact Lookup → Agent → Formatter → Platform API

Each platform has its own processor implementation:

TelegramProcessor - Bot API, HTML formatting, inline keyboards
EmailProcessor - Resend/MailChannels, HTML emails, attachments
WhatsAppProcessor - Meta Business API, templates, media support
SlackProcessor - Block Kit, threads, file uploads (planned)
DiscordProcessor - Embeds, interactions (planned)

See Gateway Processing Architecture for detailed technical documentation.

API Reference

See Gateways API for complete endpoint documentation.

Gateways ​

Overview ​

Gateway Types ​

Email ​

Telegram ​

WhatsApp ​

Slack ​

Discord ​

X.com (Twitter) ​

X.com Features ​

Posting a Tweet ​

SMS ​

Webhook ​

Creating Gateways ​

Via Dashboard ​

Via API ​

Managing Gateways ​

List Gateways ​

Get Gateway ​

Update Gateway ​

Delete Gateway ​

Sending Messages ​

Via API ​

Via Workflow ​

Receiving Messages ​

Webhook Processing ​

Message Format ​

Default Gateway ​

Gateway Status ​

Integration ​

With Contacts ​

With Conversations ​

Best Practices ​

1. Secure Credentials ​

2. Test Before Deploy ​

3. Handle Rate Limits ​

4. Log Messages ​

5. Use Templates ​

Troubleshooting ​

Messages Not Sending ​

Webhooks Not Received ​

Rate Limiting ​

Processing Architecture ​

API Reference ​

Gateways

Overview

Gateway Types

Email

Telegram

WhatsApp

Slack

Discord

X.com (Twitter)

X.com Features

Posting a Tweet

SMS

Webhook

Creating Gateways

Via Dashboard

Via API

Managing Gateways

List Gateways

Get Gateway

Update Gateway

Delete Gateway

Sending Messages

Via API

Via Workflow

Receiving Messages

Webhook Processing

Message Format

Default Gateway

Gateway Status

Integration

With Contacts

With Conversations

Best Practices

1. Secure Credentials

2. Test Before Deploy

3. Handle Rate Limits

4. Log Messages

5. Use Templates

Troubleshooting

Messages Not Sending

Webhooks Not Received

Rate Limiting

Processing Architecture

API Reference