Sign in

Ingest social mentions (system)

The system listens to the company's connected accounts, normalises what it hears into `SocialMention` records, runs sentiment analysis, fires the matching rules' actions, and pushes real-time notifications. A Marketing User reads the result in Marketing — Social inbox.

When this happens: The listening cycle (every minute) or a webhook push (X, LinkedIn, and Facebook Page and Instagram comments; X direct messages to a brand account).

How it works

  • For each network the rules name, reads what is new since its stored position: the mentions of the company's X brand accounts, the comments on its YouTube channels' videos, the comments and mentions of its LinkedIn organisations, the searches of rules that use X's keyword search, and the direct messages to its X brand accounts that allowed reading them (the newest message is asked for first and the rest read only when it is new, since X bills each one; the first reading only notes where it stands, so old messages are not read; at most every 5 minutes). Facebook Page and Instagram comments are not read but arrive by webhook. A brand account's first reading goes back seven days.
  • Deduplicates by network and the provider's message id: a duplicate is dropped without error, unless no rule matched it before and one does now. Everything fetched is kept 7 days for the rules' test (UC-13.3 ).
  • Decides which rules match (UC-13.3 BR-2). An item no rule matches is not shown in the Social inbox.
  • Classifies the sentiment of matched items (Positive / Neutral / Negative) with the AI gateway or the word lists, as the company chose, and stores the label and confidence. If the classifier is unavailable the item is stored as Unknown and classified again within the hour; a rule that filters on sentiment waits until then.
  • Resolves the author: if the author's profile is confirmed on a contact or lead, the mention is attached to that record, and a Social activity appears on that record's timeline (BR-3).
  • EasyCRM runs each matching, active rule's actions in order: notify the chosen users and roles (who hold the Social CRM permission), tag, attribute to the rule's campaign, create a lead or create a ticket. Items read as backfill are tagged and attributed but notify nobody.
  • Tells the open Social inbox pages of the company, and sends the social.mention.received event to subscribed webhooks.
  • Moves the stored position forward only when every item of the reading was stored, and counts the rule's mentions and processing time for the Listening page.

Other paths

Provider webhook push

Delivers a webhook: X (mentions and direct messages) and LinkedIn to /api/webhooks/social/{provider}, Facebook Page and Instagram comments to the Inbox's channel webhook. EasyCRM verifies the signature (HMAC for X and LinkedIn; Meta's signature for Facebook and Instagram), answers the provider at once and queues the items; steps 2–8 of the Main Flow then run in the background for each company whose account it is. The account's polled reading rests for 5 minutes after a webhook.

If something goes wrong

Provider rate limit (http 429)

Backs off until the provider says (Retry-After, X's reset time, midnight for YouTube's and LinkedIn's daily quotas), or 15 minutes. The provider's other readings in that cycle are skipped and the position is not advanced, so nothing is dropped. The company also stays within 80 % of each provider's budget. After the third cycle in a row ends this way, the rule managers are told that listening on that network is degraded; it keeps retrying.

Token expired mid-cycle

A refresh attempt fails. The 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 rows in the SocialMention table for the Social inbox. Each also has one Activity (type Social, subtype SocialMention), made the first time it concerns a contact, lead or ticket and linked to each of them, so it shows on their timelines.
  • Real-time delivery to the UI uses the existing CrmNotificationHub Redis backplane.
  • A person's own mentions are never ingested: only brand accounts' mentions and comments are heard, and an X search may run through a personal connection that allows it.
  • A user may correct a mention's sentiment in the Social inbox; the correction is kept and audited, and nothing is routed again.