Gateways API

Gateways are communication channels that allow users to interact with agents via external platforms (Telegram, Email, WhatsApp, etc.).

Endpoints

Method	Endpoint	Description
GET	/api/agents/{id}/gateways	List gateways
POST	/api/agents/{id}/gateways	Create gateway
GET	/api/agents/{id}/gateways/{gatewayId}	Get gateway
PUT	/api/agents/{id}/gateways/{gatewayId}	Update gateway
DELETE	/api/agents/{id}/gateways/{gatewayId}	Delete gateway
POST	/api/agents/{id}/gateways/{gatewayId}/verify	Verify credentials
POST	/api/agents/{id}/gateways/{gatewayId}/webhook/register	Register webhook
POST	/api/agents/{id}/gateways/{gatewayId}/webhook	Incoming webhook

List Gateways

GET /api/agents/{id}/gateways

Response

{
  "gateways": [
    {
      "id": "gateway-123",
      "type": "telegram",
      "name": "Support Bot",
      "status": "active",
      "is_default": true,
      "verified": true,
      "event_count": 1523,
      "last_event_at": "2025-01-20T10:30:00Z",
      "webhook_url": "/api/agents/{agentId}/gateways/{gatewayId}/webhook"
    }
  ]
}

Create Gateway

POST /api/agents/{id}/gateways
Content-Type: application/json

Request Body

{
  "type": "telegram",
  "name": "Support Bot",
  "config": {
    "botToken": "123456:ABC..."
  },
  "is_default": true
}

Response

{
  "id": "gateway-123",
  "type": "telegram",
  "name": "Support Bot",
  "status": "inactive",
  "webhook_url": "/api/agents/agent-1/gateways/gateway-123/webhook",
  "webhook_secret": "generated-secret-token"
}

Verify Credentials

Verify gateway credentials before activating.

POST /api/agents/{id}/gateways/{gatewayId}/verify

Response (Telegram)

{
  "success": true,
  "info": {
    "id": 123456789,
    "username": "my_support_bot",
    "firstName": "Support Bot"
  }
}

Register Webhook

Register the webhook URL with the external platform.

POST /api/agents/{id}/gateways/{gatewayId}/webhook/register

Request Body (optional)

{
  "baseUrl": "https://custom-domain.com"
}

Response

{
  "success": true,
  "webhookUrl": "https://manage.uranus.im/api/agents/agent-1/gateways/gateway-123/webhook"
}

Gateway Types

Type	Description	Config Fields
telegram	Telegram Bot	botToken
email	Email (Resend/MailChannels)	provider, fromAddress, fromName, apiKey
whatsapp	WhatsApp Business	provider, phoneNumber, accountSid, authToken
slack	Slack App	botToken, signingSecret
discord	Discord Bot	botToken, applicationId, publicKey
sms	SMS via Twilio	accountSid, authToken, phoneNumber
webhook	Custom webhook	url, secret, headers

Platform-Specific Configuration

Telegram

{
  "type": "telegram",
  "config": {
    "botToken": "123456:ABC-DEF...",
    "webhookSecret": "optional-verification-token"
  }
}

Email (Resend)

{
  "type": "email",
  "config": {
    "provider": "resend",
    "fromAddress": "[email protected]",
    "fromName": "Support Team",
    "apiKey": "re_..."
  }
}

Email (MailChannels)

{
  "type": "email",
  "config": {
    "provider": "mailchannels",
    "fromAddress": "[email protected]",
    "fromName": "Support Team"
  }
}

WhatsApp (Twilio)

{
  "type": "whatsapp",
  "config": {
    "provider": "twilio",
    "phoneNumber": "+1234567890",
    "accountSid": "AC...",
    "authToken": "..."
  }
}

Slack

{
  "type": "slack",
  "config": {
    "botToken": "xoxb-...",
    "signingSecret": "..."
  }
}

Webhook URL Structure

Each gateway gets a unique webhook URL:

/api/agents/{agentId}/gateways/{gatewayId}/webhook

This URL should be registered with the external platform (e.g., Telegram's setWebhook).

Event Tracking

Gateways track incoming events:

Field	Description
event_count	Total events received
events_today	Events received today
last_event_at	Timestamp of last event
last_error	Last error message
last_error_at	Timestamp of last error

Gateway Status

Status	Description
inactive	Not yet configured/verified
pending_verification	Awaiting credential verification
active	Verified and receiving events
error	Configuration error