Docs

Using eConnect

eConnect has two identities in every call: you, the developer, authenticated by your Empire ID key — and your end-user, identified by whatever user_id string you use internally. Your key never touches your users' personal tokens; those stay in eConnect's vault.

The REST contract (any language)

The Node SDK is just a thin wrapper — under it, every action across every platform is one of three POST endpoints, all sharing the exact same envelope shape:

POST https://econnect-api.empireunion.xyz/v1/messaging/execute   ← messaging, AI, productivity, payments
POST https://econnect-api.empireunion.xyz/v1/music/execute       ← music
POST https://econnect-api.empireunion.xyz/v1/google/execute      ← Google (Calendar, Contacts, YouTube, Sheets)

Headers — identical for all three:

Content-Type: application/json
Authorization: Bearer <your api_key>

Body — identical shape for all three:

{
  "user_id": "<whatever id you use for this end-user>",
  "action": "<see the platform's own page for exact actions>",
  "payload": { ...action-specific fields... },
  "target_app": "<see the platform's own page>"
}

A complete example — curl, sending a Telegram message:

curl -X POST https://econnect-api.empireunion.xyz/v1/messaging/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "user_id": "123456789",
    "action": "send_text",
    "payload": { "text": "Hello from eConnect!" },
    "target_app": "telegram"
  }'

A successful call returns HTTP 200 with:

{
  "success": true,
  "message": "Action 'send_text' executed securely via eConnect",
  "provider_response": { "status": "success", "platform": "telegram", "action": "send_text", "result": { ... } }
}

Important: HTTP 200 only means eConnect processed your request — it does NOT guarantee the underlying platform action succeeded. Always check provider_response.status. A platform-side failure still comes back as HTTP 200 with provider_response.status: "error" and a message explaining what went wrong — that distinction is checked on every platform page below, alongside eConnect's own HTTP-level errors (bad key, rate limits, not connected).

Install the Node SDK (optional)

npm install @empireaiorg/econnect

const EConnect = require('@empireaiorg/econnect');

const eConnect = new EConnect(
  'https://econnect-api.empireunion.xyz',
  process.env.ECONNECT_API_KEY
);

await eConnect.messaging.sendText('telegram', chatId, 'Hello!');

Every SDK method is a thin wrapper around the REST call shown above — nothing it does isn't equally reachable directly, in any language.

Connect a user's account (OAuth — Google, Spotify)

https://econnect-api.empireunion.xyz/auth/spotify/connect
  ?user_id=YOUR_INTERNAL_USER_ID
  &callback_url=https://yourapp.com/connected

eConnect handles the entire OAuth exchange itself — you never see a code to exchange. Once approved, the user is redirected to your callback_url with query params:

// success:
https://yourapp.com/connected?status=success&service=spotify
// failure:
https://yourapp.com/connected?status=error&message=Some+error+description

Bring your own platform credentials

For platforms like Telegram, Discord, OpenAI, or Trello, add your own bot token or API key once on your Connections page — messages and actions then go out through your own account, not a shared one. Each platform's page below shows exactly where to find those credentials.

Every platform, in detail

Rate limits & quotas

Every plan has a monthly request allowance and a per-minute rate limit. Both reset at the start of each billing cycle. Check your current usage anytime on your dashboard.