SocialOps

SocialOps is a unified inbox service for social messages, IM channels, developer events, and operational webhooks. The current MVP supports inbound aggregation, normalized threads, message storage, filtering, console review, internal notes, outbound reply queues, and per-message billing.

Status

Backend and console MVP are available. The first provider allowlist is:

Provider	Status	Notes
generic-webhook	Available	Generic JSON event ingestion.
telegram	Available for normalized ingestion and scheduled reply delivery	Requires a telegram-bot Connected Account and an active SocialOps channel binding.
github	Available for normalized ingestion	Useful for issue, PR, and workflow events.

Slack, Discord, Teams, X/Twitter, Meta, Instagram, WhatsApp, and LINE are planned through the Connected Accounts module and provider-specific webhooks. Outbound replies are stored as SocialOps actions; unsupported providers are marked failed with an audit error instead of being silently dropped.

Console

After creating a socialops service instance, open:

Console > SocialOps

The console can:

• List SocialOps service instances.
• Filter threads by status, priority, provider, and search query.
• Inspect normalized thread messages without exposing raw provider payloads.
• Bind Telegram Bot connections to SocialOps chat/channel targets.
• Update thread status, priority, and assignee.
• Queue outbound replies for provider adapter delivery.
• Add internal notes to preserve handling history.

Console management endpoints use the user JWT and service:read or service:manage permissions:

GET   /console/socialops/instances
GET   /console/socialops/:alias/channels
POST  /console/socialops/:alias/channels
PATCH /console/socialops/:alias/channels/:channel_id
GET   /console/socialops/:alias/inbox
GET   /console/socialops/:alias/threads/:thread_id/messages
POST  /console/socialops/:alias/threads/:thread_id/notes
POST  /console/socialops/:alias/threads/:thread_id/replies
PATCH /console/socialops/:alias/threads/:thread_id

Create a Telegram channel binding:

{
  "provider": "telegram",
  "connected_account_id": "conn_xxx",
  "channel_name": "Support Telegram",
  "external_channel_id": "-1001234567890",
  "parse_mode": "HTML"
}

The connected_account_id must reference an active telegram-bot Connected Account owned by the same user. Channel bindings can be toggled with:

{
  "status": "inactive"
}

Create an internal note:

{
  "text": "Checked provider dashboard and assigned to ops."
}

Notes are stored as internal SocialOps messages. They do not send anything to external providers.

Queue an outbound reply:

{
  "text": "Thanks, we are checking this now."
}

Replies are stored as outbound SocialOps messages and create a send_reply action with pending status. The scheduled delivery worker consumes pending actions, sends supported providers, and marks each action as completed or failed.

Endpoints

POST /v1/apps/socialops/:alias/webhook/:provider
GET  /v1/apps/socialops/:alias/inbox
GET  /v1/apps/socialops/:alias/threads
GET  /v1/apps/socialops/:alias/threads/:thread_id/messages
POST /v1/apps/socialops/:alias/threads/:thread_id/replies

Required scopes:

socialops:write
socialops:read

Ingest an Event

curl -X POST https://api.open4x.com/v1/apps/socialops/support/webhook/generic-webhook \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_1001",
    "thread_id": "incident_42",
    "title": "Incident opened",
    "text": "API latency is high",
    "user": {
      "id": "monitor"
    },
    "labels": ["ops", "urgent"]
  }'

Response:

{
  "status": "accepted",
  "provider": "generic-webhook",
  "thread_id": "soth_...",
  "message_id": "somsg_..."
}

Query Inbox

curl "https://api.open4x.com/v1/apps/socialops/support/inbox?status=open&priority=high&limit=50" \
  -H "X-API-Key: sk_xxx"

Supported filters:

Query	Values
status	open, pending, resolved, archived
priority	low, normal, high, urgent
provider	generic-webhook, telegram, github
q	Searches thread subject and AI summary.
page, limit	Standard pagination; limit is capped at 100.

Queue a Reply

curl -X POST https://api.open4x.com/v1/apps/socialops/support/threads/soth_xxx/replies \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thanks, we are checking this now."
  }'

Response:

{
  "success": true,
  "data": {
    "message": {
      "direction": "outbound",
      "message_type": "text",
      "text": "Thanks, we are checking this now."
    },
    "action": {
      "action_type": "send_reply",
      "status": "pending"
    }
  }
}

Reply Delivery

The scheduled worker scans send_reply actions and currently supports Telegram delivery:

1. The action is claimed as processing.
2. The worker loads the thread, outbound message, and active SocialOps channel.
3. The channel must reference an active telegram-bot Connected Account.
4. The worker charges the SocialOps reply delivery fee.
5. Telegram sendMessage is called with the thread chat id.
6. On success, the action becomes completed and the outbound message stores the Telegram message_id.
7. On provider failure, the charge is refunded and the action becomes failed.

If a channel, connected account, balance, or provider adapter is missing, the action is marked failed with an audit error.

Data Safety

Inbox responses do not expose external thread identifiers by default. Message responses also hide raw provider payloads by default. Raw payloads are retained for auditing and future provider-specific processing, but should not be shown in normal customer-facing UI.

Billing

Inbound SocialOps messages are charged per accepted webhook event. The MVP default rate is 0.0002 USD per inbound message. Telegram reply delivery is charged when the scheduled worker actually sends the message; failed provider sends are refunded.