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
• SMS - Twilio/providers
• Webhook - Custom HTTP endpoints

Gateway Types

Email

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

Telegram

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

WhatsApp

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

Slack

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

Discord

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

SMS

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

Webhook

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

Creating Gateways

Via Dashboard

1. Navigate to Services
2. Click Add Gateway
3. Select type
4. Configure credentials
5. Test connection
6. Save

Via API

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

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

Get Gateway

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

Update Gateway

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

Delete Gateway

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

Sending Messages

Via API

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

{
  "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

{
  "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:

{
  "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:

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

With Conversations

Messages are grouped by conversation:

{
  "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

1. Verify credentials
2. Check gateway status
3. Review error logs
4. Test with simple message

Webhooks Not Received

1. Verify webhook URL
2. Check authentication
3. Review server logs
4. Test with curl

Rate Limiting

1. Reduce message frequency
2. Implement queuing
3. Contact provider
4. Use multiple gateways

API Reference

See Gateways API for complete endpoint documentation.