Sign in

Ingest social mentions (system)

The system periodically polls connected providers for new mentions matching active listening rules, normalises them into `SocialMention` records, runs sentiment analysis, fires rule-defined actions, and pushes real-time notifications.

When this happens: Polling interval (default 60 s) or webhook push (where the provider supports it).

How it works

  • For each (Connection, ActiveRules) pair, requests new items since LastSyncCursor using the provider's incremental endpoint.
  • Deduplicates by (Provider, ExternalMessageId) — duplicates are dropped without error.
  • Resolves the author against SocialProfileLink. If the author already links to a Contact/Lead, the mention is attached to that record.
  • EasyCRM runs sentiment classification (Positive / Neutral / Negative) via the configured analyser. EasyCRM stores score and label on SocialMention. (UC-13.9 / FR-13-010)
  • EasyCRM evaluates each matched rule's actions in order: create Lead, create Ticket, notify users, tag, attribute to Campaign.
  • Emits a SignalR event socialMention.received on CrmNotificationHub to users subscribed to the rule's notification group.
  • EasyCRM updates Connection.LastSyncCursor, increments per-rule counters used by the Dashboard tile.

Other paths

Provider webhook push

Delivers a webhook to /api/webhooks/social/{provider}. EasyCRM verifies the provider signature (HMAC for X, Meta App Secret Proof for Facebook/Instagram, TikTok event-webhook signature), then runs steps 2–7 of the Main Flow synchronously. Webhook-driven providers therefore deliver near-real-time mentions; polling-only providers honour the 60-second cycle.

If something goes wrong

Provider rate limit (http 429)

Backs off honouring Retry-After. Subsequent rules for the same connection in the same cycle are skipped — cursor is *not* advanced, so nothing is dropped.

Token expired mid-cycle

A refresh attempt fails. Connection moves to RequiresReauth (UC-13.1 ). Other connections continue to ingest normally.

Invalid webhook signature

EasyCRM returns HTTP 400. EasyCRM logs a security event. The provider's retry policy applies.

Good to know

  • Mentions are deduplicated by (Provider, ExternalMessageId) — the same post is never ingested twice.
  • Ingestion is idempotent; replaying the same webhook event yields no new records.
  • Mentions are stored as Activity records of type SocialMention *and* as rows in the SocialMention projection table for inbox queries.
  • Real-time delivery to the UI uses the existing CrmNotificationHub Redis backplane.