autopilot-core-sandbox 0.0.1

package/dist/dist/migrations/20260826234722_facebook_messenger_ingestion.sql

@@ -0,0 +1,703 @@
+-- Facebook Messenger ingestion: conversation state, durable webhook receipt,
+-- unified-inbox message rows, ad-referral lead creation, and the instant
+-- greeting claim.
+--
+-- Mirrors the Meta Lead Ads ingestion architecture: everything in this
+-- migration is additive and fail-closed. Messenger sync is disabled for
+-- every existing company until a server route validates and enables the
+-- configuration through set_facebook_messenger_settings(). The companion
+-- RLS migration keeps the webhook receipt queue service-role only and makes
+-- conversations read-only for company members (the unified inbox).
+--
+-- Message content itself lives in the existing public.message table, keyed
+-- by a synthetic thread key ('fbm:<page_id>:<psid>') in client_number and a
+-- synthetic line key ('fbm:<page_id>') in user_number, so the entire thread
+-- stack (get_message_threads_page, get_messages_page, unread counts,
+-- realtime, mark-read) works for Messenger without modification.
+
+-- ============================================================
+-- Existing-table additions
+-- ============================================================
+
+alter table "public"."settings_facebook_ads"
+    add column if not exists "messenger_sync_enabled" boolean
+        default false not null,
+    add column if not exists "messenger_greeting_enabled" boolean
+        default false not null,
+    -- Sent verbatim (no template variables) by the processor the moment an
+    -- ad-referral conversation receives its first message.
+    add column if not exists "messenger_greeting_template" text;
+
+alter table "public"."settings_facebook_ads"
+    add constraint "settings_facebook_ads_messenger_sync_source_check"
+        check (not "messenger_sync_enabled" or "source_id" is not null),
+    add constraint "settings_facebook_ads_messenger_greeting_check"
+        check (
+            not "messenger_greeting_enabled"
+            or nullif(btrim("messenger_greeting_template"), '') is not null
+        );
+
+-- Meta message id (mid) on the unified message table. Dedupes our own Send
+-- API writes against their message_echoes webhook, and Business-Suite sends
+-- against reprocessed webhook receipts.
+-- A plain unique constraint (NULLs are distinct, so SMS rows never
+-- conflict) rather than a partial index: PostgREST's upsert on_conflict
+-- can only infer a full constraint.
+alter table "public"."message"
+    add column if not exists "meta_message_id" text,
+    add constraint "message_meta_message_id_key" unique ("meta_message_id");
+
+-- ============================================================
+-- Conversation state
+-- ============================================================
+
+create table if not exists "public"."facebook_messenger_conversation" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "updated_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    -- Nullable so disconnecting a Page erases its token without erasing the
+    -- conversation history behind the inbox threads.
+    "page_id" uuid,
+    "meta_page_id" text not null,
+    -- Page-scoped user id: Meta's stable identity for this person on this
+    -- Page. Never a phone number.
+    "psid" text not null,
+    -- Snapshot so threads stay labeled after a Page disconnect.
+    "page_name" text not null,
+    -- The message.client_number value for this conversation's thread.
+    "thread_key" text not null,
+    "client_id" uuid,
+    "profile_name" text,
+    "profile_pic_url" text,
+    -- ad_referral = arrived from a click-to-Messenger ad (carries ad ids and
+    -- auto-creates a lead); organic = messaged the Page directly.
+    "source" text default 'organic' not null,
+    "meta_ad_id" text,
+    "meta_adset_id" text,
+    "meta_campaign_id" text,
+    "referral_ref" text,
+    -- Advances on every inbound customer message; the send routes compare it
+    -- against Meta's 24-hour standard messaging window.
+    "last_user_message_at" timestamp with time zone,
+    "last_page_message_at" timestamp with time zone,
+    -- The at-most-once claim for the instant greeting (set atomically by
+    -- finalize before the Send API call; a failed send never re-greets).
+    "greeting_sent_at" timestamp with time zone,
+    constraint "facebook_messenger_conversation_pkey" primary key ("id"),
+    constraint "facebook_messenger_conversation_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_messenger_conversation_page_psid_key"
+        unique ("meta_page_id", "psid"),
+    constraint "facebook_messenger_conversation_thread_key_key"
+        unique ("thread_key"),
+    constraint "facebook_messenger_conversation_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_messenger_conversation_company_page_fkey"
+        foreign key ("company_id", "page_id")
+        references "public"."facebook_ads_lead_page"("company_id", "id")
+        on delete set null ("page_id"),
+    constraint "facebook_messenger_conversation_client_id_fkey"
+        foreign key ("client_id") references "public"."client"("id")
+        on delete set null,
+    constraint "facebook_messenger_conversation_meta_page_id_check"
+        check ("meta_page_id" ~ '^[0-9]+$'),
+    constraint "facebook_messenger_conversation_psid_check"
+        check ("psid" ~ '^[0-9]+$'),
+    constraint "facebook_messenger_conversation_page_name_check"
+        check (nullif(btrim("page_name"), '') is not null),
+    constraint "facebook_messenger_conversation_thread_key_check"
+        check ("thread_key" = 'fbm:' || "meta_page_id" || ':' || "psid"),
+    constraint "facebook_messenger_conversation_source_check"
+        check ("source" in ('ad_referral', 'organic')),
+    constraint "facebook_messenger_conversation_meta_ad_id_check"
+        check ("meta_ad_id" is null or "meta_ad_id" ~ '^[0-9]+$'),
+    constraint "facebook_messenger_conversation_meta_adset_id_check"
+        check ("meta_adset_id" is null or "meta_adset_id" ~ '^[0-9]+$'),
+    constraint "facebook_messenger_conversation_meta_campaign_id_check"
+        check ("meta_campaign_id" is null or "meta_campaign_id" ~ '^[0-9]+$')
+);
+
+alter table "public"."facebook_messenger_conversation" owner to "postgres";
+
+create index if not exists "facebook_messenger_conversation_company_idx"
+    on "public"."facebook_messenger_conversation"
+    ("company_id", "created_at" desc);
+
+create index if not exists "facebook_messenger_conversation_client_idx"
+    on "public"."facebook_messenger_conversation" ("client_id")
+    where "client_id" is not null;
+
+create or replace trigger "set_facebook_messenger_conversation_updated_at_trigger"
+before update on "public"."facebook_messenger_conversation"
+for each row execute function "public"."set_facebook_ads_updated_at"();
+
+-- ============================================================
+-- Durable webhook receipt queue
+-- ============================================================
+
+create table if not exists "public"."facebook_messenger_event" (
+    "id" uuid default gen_random_uuid() not null,
+    "created_at" timestamp with time zone default now() not null,
+    "updated_at" timestamp with time zone default now() not null,
+    "company_id" uuid not null,
+    "page_id" uuid,
+    "meta_page_id" text not null,
+    "psid" text not null,
+    -- message = inbound customer message; echo = a message the Page sent
+    -- (our Send API, Business Suite, or the mobile Pages app); postback =
+    -- button tap (Get Started); referral = ad/link attribution for an
+    -- existing conversation.
+    "event_kind" text not null,
+    -- Meta message id when the event carries one (message/echo).
+    "mid" text,
+    -- mid when present, otherwise a synthetic '<psid>:<timestamp>:<kind>'.
+    "dedupe_key" text not null,
+    "meta_timestamp" timestamp with time zone not null,
+    "webhook_payload" jsonb not null,
+    "conversation_id" uuid,
+    "message_id" uuid,
+    "status" text default 'pending' not null,
+    "skip_reason" text,
+    "received_count" integer default 1 not null,
+    "last_received_at" timestamp with time zone default now() not null,
+    "attempt_count" integer default 0 not null,
+    "next_attempt_at" timestamp with time zone default now() not null,
+    "last_attempt_at" timestamp with time zone,
+    "processed_at" timestamp with time zone,
+    "last_error" text,
+    constraint "facebook_messenger_event_pkey" primary key ("id"),
+    constraint "facebook_messenger_event_company_id_id_key"
+        unique ("company_id", "id"),
+    constraint "facebook_messenger_event_dedupe_key"
+        unique ("meta_page_id", "dedupe_key"),
+    constraint "facebook_messenger_event_company_id_fkey"
+        foreign key ("company_id") references "public"."company"("id")
+        on delete cascade,
+    constraint "facebook_messenger_event_company_page_fkey"
+        foreign key ("company_id", "page_id")
+        references "public"."facebook_ads_lead_page"("company_id", "id")
+        on delete set null ("page_id"),
+    constraint "facebook_messenger_event_conversation_fkey"
+        foreign key ("conversation_id")
+        references "public"."facebook_messenger_conversation"("id")
+        on delete set null,
+    constraint "facebook_messenger_event_message_fkey"
+        foreign key ("message_id") references "public"."message"("id")
+        on delete set null,
+    constraint "facebook_messenger_event_meta_page_id_check"
+        check ("meta_page_id" ~ '^[0-9]+$'),
+    constraint "facebook_messenger_event_psid_check"
+        check ("psid" ~ '^[0-9]+$'),
+    constraint "facebook_messenger_event_kind_check"
+        check ("event_kind" in ('message', 'echo', 'postback', 'referral')),
+    constraint "facebook_messenger_event_dedupe_key_check"
+        check (nullif(btrim("dedupe_key"), '') is not null),
+    constraint "facebook_messenger_event_webhook_payload_check"
+        check (jsonb_typeof("webhook_payload") = 'object'),
+    constraint "facebook_messenger_event_status_check"
+        check (
+            "status" in ('pending', 'processing', 'processed', 'skipped', 'dead')
+        ),
+    constraint "facebook_messenger_event_received_count_check"
+        check ("received_count" > 0),
+    constraint "facebook_messenger_event_attempt_count_check"
+        check ("attempt_count" >= 0),
+    constraint "facebook_messenger_event_processed_at_check"
+        check ("status" <> 'processed' or "processed_at" is not null)
+);
+
+alter table "public"."facebook_messenger_event" owner to "postgres";
+
+create index if not exists "facebook_messenger_event_due_idx"
+    on "public"."facebook_messenger_event" ("next_attempt_at", "created_at")
+    where "status" = 'pending';
+
+create index if not exists "facebook_messenger_event_company_history_idx"
+    on "public"."facebook_messenger_event" ("company_id", "created_at" desc);
+
+create or replace trigger "set_facebook_messenger_event_updated_at_trigger"
+before update on "public"."facebook_messenger_event"
+for each row execute function "public"."set_facebook_ads_updated_at"();
+
+-- ============================================================
+-- Settings RPC
+-- ============================================================
+
+create or replace function "public"."set_facebook_messenger_settings"("p" jsonb)
+returns void
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_company_id" uuid := ("p" ->> 'company_id')::uuid;
+    "v_current" "public"."settings_facebook_ads"%rowtype;
+    "v_sync_enabled" boolean;
+    "v_greeting_enabled" boolean;
+    "v_greeting_template" text;
+begin
+    if jsonb_typeof("p") <> 'object' or "v_company_id" is null then
+        raise exception 'company_id and an object payload are required'
+            using errcode = '22023';
+    end if;
+
+    if not exists (
+        select 1 from "public"."company" where "id" = "v_company_id"
+    ) then
+        raise exception 'Company does not exist' using errcode = '23503';
+    end if;
+
+    insert into "public"."settings_facebook_ads" ("company_id")
+    values ("v_company_id")
+    on conflict ("company_id") do nothing;
+
+    select * into "v_current"
+    from "public"."settings_facebook_ads"
+    where "company_id" = "v_company_id"
+    for update;
+
+    "v_sync_enabled" := case when "p" ? 'messenger_sync_enabled'
+        then coalesce(("p" ->> 'messenger_sync_enabled')::boolean, false)
+        else "v_current"."messenger_sync_enabled" end;
+    "v_greeting_enabled" := case when "p" ? 'messenger_greeting_enabled'
+        then coalesce(("p" ->> 'messenger_greeting_enabled')::boolean, false)
+        else "v_current"."messenger_greeting_enabled" end;
+    "v_greeting_template" := case when "p" ? 'messenger_greeting_template'
+        then nullif(btrim("p" ->> 'messenger_greeting_template'), '')
+        else "v_current"."messenger_greeting_template" end;
+
+    if "v_sync_enabled" and "v_current"."source_id" is null then
+        raise exception 'A Facebook Ads lead source is required before enabling Messenger sync'
+            using errcode = '23514';
+    end if;
+
+    if "v_greeting_enabled" and "v_greeting_template" is null then
+        raise exception 'The instant greeting requires a message'
+            using errcode = '23514';
+    end if;
+
+    update "public"."settings_facebook_ads"
+    set
+        "messenger_sync_enabled" = "v_sync_enabled",
+        "messenger_greeting_enabled" = "v_greeting_enabled",
+        "messenger_greeting_template" = "v_greeting_template"
+    where "company_id" = "v_company_id";
+end;
+$$;
+
+alter function "public"."set_facebook_messenger_settings"(jsonb)
+owner to "postgres";
+
+-- ============================================================
+-- Receipt, claim, and finalization RPCs
+-- ============================================================
+
+create or replace function "public"."enqueue_facebook_messenger_event"("p" jsonb)
+returns jsonb
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_page" "public"."facebook_ads_lead_page"%rowtype;
+    "v_settings" "public"."settings_facebook_ads"%rowtype;
+    "v_accepted" boolean := false;
+    "v_reason" text;
+    "v_event_id" uuid;
+    "v_received_count" integer;
+    "v_status" text;
+    "v_return_reason" text;
+    "v_webhook_payload" jsonb := coalesce("p" -> 'webhook_payload', '{}'::jsonb);
+begin
+    if jsonb_typeof("p") <> 'object'
+       or jsonb_typeof("v_webhook_payload") <> 'object'
+       or coalesce("p" ->> 'meta_page_id', '') !~ '^[0-9]+$'
+       or coalesce("p" ->> 'psid', '') !~ '^[0-9]+$'
+       or coalesce("p" ->> 'event_kind', '')
+           not in ('message', 'echo', 'postback', 'referral')
+       or nullif(btrim(coalesce("p" ->> 'dedupe_key', '')), '') is null
+       or "p" ->> 'meta_timestamp' is null
+    then
+        raise exception 'Valid Meta Page, PSID, kind, dedupe key, timestamp, and payload are required'
+            using errcode = '22023';
+    end if;
+
+    select * into "v_page"
+    from "public"."facebook_ads_lead_page"
+    where "meta_page_id" = "p" ->> 'meta_page_id';
+
+    if not found then
+        return jsonb_build_object(
+            'event_id', null,
+            'accepted', false,
+            'duplicate', false,
+            'reason', 'page_not_configured'
+        );
+    end if;
+
+    select * into "v_settings"
+    from "public"."settings_facebook_ads"
+    where "company_id" = "v_page"."company_id";
+
+    "v_accepted" := "v_page"."is_enabled"
+        and "v_page"."subscription_status" = 'subscribed'
+        and coalesce("v_settings"."messenger_sync_enabled", false);
+
+    "v_reason" := case
+        when not "v_page"."is_enabled" then 'page_disabled'
+        when "v_page"."subscription_status" <> 'subscribed'
+            then 'page_not_subscribed'
+        when not coalesce("v_settings"."messenger_sync_enabled", false)
+            then 'messenger_sync_disabled'
+        else null
+    end;
+
+    insert into "public"."facebook_messenger_event" (
+        "company_id", "page_id", "meta_page_id", "psid", "event_kind",
+        "mid", "dedupe_key", "meta_timestamp", "webhook_payload",
+        "status", "skip_reason"
+    ) values (
+        "v_page"."company_id",
+        "v_page"."id",
+        "p" ->> 'meta_page_id',
+        "p" ->> 'psid',
+        "p" ->> 'event_kind',
+        nullif(btrim(coalesce("p" ->> 'mid', '')), ''),
+        btrim("p" ->> 'dedupe_key'),
+        ("p" ->> 'meta_timestamp')::timestamp with time zone,
+        "v_webhook_payload",
+        case when "v_accepted" then 'pending' else 'skipped' end,
+        "v_reason"
+    )
+    on conflict ("meta_page_id", "dedupe_key") do update
+    set
+        "received_count" = "facebook_messenger_event"."received_count" + 1,
+        "last_received_at" = now()
+    returning "id", "received_count", "status", "skip_reason"
+    into "v_event_id", "v_received_count", "v_status", "v_return_reason";
+
+    return jsonb_build_object(
+        'event_id', "v_event_id",
+        'accepted', "v_status" <> 'skipped',
+        'duplicate', "v_received_count" > 1,
+        'reason', "v_return_reason"
+    );
+end;
+$$;
+
+alter function "public"."enqueue_facebook_messenger_event"(jsonb)
+owner to "postgres";
+
+create or replace function "public"."claim_facebook_messenger_events"(
+    "batch_size" integer
+)
+returns setof "public"."facebook_messenger_event"
+language sql
+security definer
+set search_path = ''
+as $$
+    update "public"."facebook_messenger_event"
+    set
+        "status" = 'processing',
+        "attempt_count" = "attempt_count" + 1,
+        "last_attempt_at" = now()
+    where "id" in (
+        select "id"
+        from "public"."facebook_messenger_event"
+        where "status" = 'pending' and "next_attempt_at" <= now()
+        order by "next_attempt_at", "created_at"
+        limit least(greatest(coalesce("batch_size", 0), 0), 100)
+        for update skip locked
+    )
+    returning *;
+$$;
+
+alter function "public"."claim_facebook_messenger_events"(integer)
+owner to "postgres";
+
+-- The atomic heart of ingestion. One call per claimed event: upsert the
+-- conversation, create the ad-referral lead (with its automation events),
+-- write the unified-inbox message row, claim the instant greeting, and mark
+-- the event processed — all or nothing.
+create or replace function "public"."finalize_facebook_messenger_event"("p" jsonb)
+returns jsonb
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+    "v_event" "public"."facebook_messenger_event"%rowtype;
+    "v_settings" "public"."settings_facebook_ads"%rowtype;
+    "v_page" "public"."facebook_ads_lead_page"%rowtype;
+    "v_conversation" "public"."facebook_messenger_conversation"%rowtype;
+    "v_is_new" boolean := false;
+    "v_client_created" boolean := false;
+    "v_greeting_claimed" boolean := false;
+    "v_owner_user_id" uuid;
+    "v_message_id" uuid;
+    "v_content" text := nullif(btrim(coalesce("p" ->> 'content', '')), '');
+    "v_image_url" text := nullif(btrim(coalesce("p" ->> 'image_url', '')), '');
+    "v_video_url" text := nullif(btrim(coalesce("p" ->> 'video_url', '')), '');
+    "v_profile_name" text :=
+        nullif(btrim(coalesce("p" ->> 'profile_name', '')), '');
+    "v_profile_pic_url" text :=
+        nullif(btrim(coalesce("p" ->> 'profile_pic_url', '')), '');
+    "v_referral_ad_id" text := nullif("p" ->> 'meta_ad_id', '');
+    "v_referral_adset_id" text := nullif("p" ->> 'meta_adset_id', '');
+    "v_referral_campaign_id" text := nullif("p" ->> 'meta_campaign_id', '');
+    "v_referral_ref" text := nullif(btrim(coalesce("p" ->> 'referral_ref', '')), '');
+    "v_has_referral" boolean := coalesce(("p" ->> 'has_referral')::boolean, false);
+    "v_first_name" text;
+    "v_last_name" text;
+begin
+    if jsonb_typeof("p") <> 'object' or ("p" ->> 'event_id') is null then
+        raise exception 'event_id and an object payload are required'
+            using errcode = '22023';
+    end if;
+
+    select * into "v_event"
+    from "public"."facebook_messenger_event"
+    where "id" = ("p" ->> 'event_id')::uuid
+    for update;
+
+    if not found or "v_event"."status" <> 'processing' then
+        raise exception 'Messenger event is not claimed for processing'
+            using errcode = '22023';
+    end if;
+
+    select * into "v_settings"
+    from "public"."settings_facebook_ads"
+    where "company_id" = "v_event"."company_id";
+
+    select * into "v_page"
+    from "public"."facebook_ads_lead_page"
+    where "meta_page_id" = "v_event"."meta_page_id";
+
+    select * into "v_conversation"
+    from "public"."facebook_messenger_conversation"
+    where "meta_page_id" = "v_event"."meta_page_id"
+      and "psid" = "v_event"."psid"
+    for update;
+
+    if not found then
+        "v_is_new" := true;
+        insert into "public"."facebook_messenger_conversation" (
+            "company_id", "page_id", "meta_page_id", "psid", "page_name",
+            "thread_key", "profile_name", "profile_pic_url", "source",
+            "meta_ad_id", "meta_adset_id", "meta_campaign_id", "referral_ref"
+        ) values (
+            "v_event"."company_id",
+            "v_event"."page_id",
+            "v_event"."meta_page_id",
+            "v_event"."psid",
+            coalesce("v_page"."page_name", 'Facebook Page'),
+            'fbm:' || "v_event"."meta_page_id" || ':' || "v_event"."psid",
+            "v_profile_name",
+            "v_profile_pic_url",
+            case when "v_has_referral" then 'ad_referral' else 'organic' end,
+            "v_referral_ad_id",
+            "v_referral_adset_id",
+            "v_referral_campaign_id",
+            "v_referral_ref"
+        ) returning * into "v_conversation";
+    else
+        update "public"."facebook_messenger_conversation"
+        set
+            "profile_name" = coalesce("v_profile_name", "profile_name"),
+            "profile_pic_url" =
+                coalesce("v_profile_pic_url", "profile_pic_url"),
+            -- A referral arriving later upgrades an organic conversation to
+            -- ad_referral; attribution is never downgraded or overwritten.
+            "source" = case
+                when "v_has_referral" and "source" = 'organic'
+                    then 'ad_referral'
+                else "source"
+            end,
+            "meta_ad_id" = coalesce("meta_ad_id", "v_referral_ad_id"),
+            "meta_adset_id" = coalesce("meta_adset_id", "v_referral_adset_id"),
+            "meta_campaign_id" =
+                coalesce("meta_campaign_id", "v_referral_campaign_id"),
+            "referral_ref" = coalesce("referral_ref", "v_referral_ref")
+        where "id" = "v_conversation"."id"
+        returning * into "v_conversation";
+    end if;
+
+    if "v_event"."event_kind" = 'message' then
+        update "public"."facebook_messenger_conversation"
+        set "last_user_message_at" = greatest(
+            coalesce("last_user_message_at", "v_event"."meta_timestamp"),
+            "v_event"."meta_timestamp"
+        )
+        where "id" = "v_conversation"."id"
+        returning * into "v_conversation";
+    elsif "v_event"."event_kind" = 'echo' then
+        update "public"."facebook_messenger_conversation"
+        set "last_page_message_at" = greatest(
+            coalesce("last_page_message_at", "v_event"."meta_timestamp"),
+            "v_event"."meta_timestamp"
+        )
+        where "id" = "v_conversation"."id"
+        returning * into "v_conversation";
+    end if;
+
+    -- Ad-referral conversations become leads (Andrew's locked policy:
+    -- organic DMs stay inbox-only). The client insert fires the existing
+    -- capture_automation_lead_created trigger (generic branch), and the
+    -- dedicated messenger_conversation_started event below carries the
+    -- conversation for messenger_client automation actions.
+    if "v_conversation"."client_id" is null
+       and "v_conversation"."source" = 'ad_referral'
+       and "v_event"."event_kind" in ('message', 'postback')
+       and coalesce("v_settings"."messenger_sync_enabled", false)
+       and "v_settings"."source_id" is not null
+    then
+        "v_first_name" := nullif(
+            btrim(split_part(coalesce("v_conversation"."profile_name", ''), ' ', 1)),
+            ''
+        );
+        "v_last_name" := nullif(btrim(substr(
+            coalesce("v_conversation"."profile_name", ''),
+            length(split_part(coalesce("v_conversation"."profile_name", ''), ' ', 1)) + 1
+        )), '');
+
+        insert into "public"."client" (
+            "company_id", "first_name", "last_name", "client_or_lead",
+            "source_id", "created_via",
+            "is_do_not_marketing_sms", "is_do_not_marketing_email"
+        ) values (
+            "v_event"."company_id",
+            "v_first_name",
+            "v_last_name",
+            'lead'::"public"."client_or_lead_enum",
+            "v_settings"."source_id",
+            'facebook_messenger',
+            -- No consent evidence exists for a Messenger conversation, so
+            -- both marketing channels start suppressed.
+            true,
+            true
+        ) returning "id" into "v_conversation"."client_id";
+
+        update "public"."facebook_messenger_conversation"
+        set "client_id" = "v_conversation"."client_id"
+        where "id" = "v_conversation"."id";
+
+        if "v_settings"."lead_tag_id" is not null and exists (
+            select 1 from "public"."client_tag"
+            where "id" = "v_settings"."lead_tag_id"
+              and "company_id" = "v_event"."company_id"
+        ) then
+            insert into "public"."client_tag_link" (
+                "company_id", "client_id", "client_tag_id"
+            ) values (
+                "v_event"."company_id",
+                "v_conversation"."client_id",
+                "v_settings"."lead_tag_id"
+            );
+        end if;
+
+        insert into "public"."automation_event" (
+            "company_id", "event_type", "client_id", "payload"
+        ) values (
+            "v_event"."company_id",
+            'messenger_conversation_started',
+            "v_conversation"."client_id",
+            jsonb_build_object(
+                'created_via', 'facebook_messenger',
+                'conversation_id', "v_conversation"."id",
+                'thread_key', "v_conversation"."thread_key",
+                'meta_ad_id', "v_conversation"."meta_ad_id",
+                'meta_adset_id', "v_conversation"."meta_adset_id",
+                'meta_campaign_id', "v_conversation"."meta_campaign_id"
+            )
+        );
+
+        "v_client_created" := true;
+    end if;
+
+    -- The unified-inbox row. message.user_id is NOT NULL, so a company with
+    -- no owner (role_id=1) gets no thread row rather than a constraint
+    -- violation — the same trade the automation SMS sender makes.
+    if "v_event"."event_kind" in ('message', 'echo')
+       and ("v_content" is not null
+            or "v_image_url" is not null
+            or "v_video_url" is not null)
+    then
+        select "user_id" into "v_owner_user_id"
+        from "public"."user_role"
+        where "company_id" = "v_event"."company_id" and "role_id" = 1
+        limit 1;
+
+        if "v_owner_user_id" is not null then
+            insert into "public"."message" (
+                "company_id", "user_id", "client_id", "client_number",
+                "user_number", "content", "image", "video", "inbound",
+                "sent", "received", "pending", "read", "system",
+                "meta_message_id"
+            ) values (
+                "v_event"."company_id",
+                "v_owner_user_id",
+                "v_conversation"."client_id",
+                "v_conversation"."thread_key",
+                'fbm:' || "v_event"."meta_page_id",
+                coalesce("v_content", ''),
+                "v_image_url",
+                "v_video_url",
+                "v_event"."event_kind" = 'message',
+                true,
+                true,
+                false,
+                "v_event"."event_kind" = 'echo',
+                false,
+                "v_event"."mid"
+            )
+            on conflict ("meta_message_id") do nothing
+            returning "id" into "v_message_id";
+        end if;
+    end if;
+
+    -- Instant greeting: claimed atomically here (greeting_sent_at flips
+    -- exactly once), sent by the processor right after this call returns.
+    -- At-most-once by design — a failed Send API call never re-greets.
+    if "v_event"."event_kind" = 'message'
+       and "v_conversation"."source" = 'ad_referral'
+       and "v_conversation"."greeting_sent_at" is null
+       and coalesce("v_settings"."messenger_greeting_enabled", false)
+       and nullif(btrim(coalesce(
+           "v_settings"."messenger_greeting_template", '')), '') is not null
+    then
+        update "public"."facebook_messenger_conversation"
+        set "greeting_sent_at" = now()
+        where "id" = "v_conversation"."id"
+          and "greeting_sent_at" is null;
+        "v_greeting_claimed" := found;
+    end if;
+
+    update "public"."facebook_messenger_event"
+    set
+        "conversation_id" = "v_conversation"."id",
+        "message_id" = "v_message_id",
+        "processed_at" = now(),
+        "status" = 'processed',
+        "skip_reason" = null,
+        "last_error" = null
+    where "id" = "v_event"."id";
+
+    return jsonb_build_object(
+        'conversation_id', "v_conversation"."id",
+        'client_id', "v_conversation"."client_id",
+        'message_id', "v_message_id",
+        'is_new_conversation', "v_is_new",
+        'client_created', "v_client_created",
+        'greeting_claimed', "v_greeting_claimed",
+        'greeting_template', case when "v_greeting_claimed"
+            then "v_settings"."messenger_greeting_template" else null end,
+        'psid', "v_conversation"."psid",
+        'thread_key', "v_conversation"."thread_key"
+    );
+end;
+$$;
+
+alter function "public"."finalize_facebook_messenger_event"(jsonb)
+owner to "postgres";