👁82views

The Hitchhikers Guide to Fixing Why a Thumbnail Image Does Not Show for Your Article on WhatsApp, LinkedIn, Twitter or Instagram

<meta property="og:title" content="Your Page Title" />
<meta property="og:description" content="A brief description" />
<meta property="og:image" content="https://example.com/image.jpg" />
<meta property="og:url" content="https://example.com/page" />
<meta property="og:type" content="article" />

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://example.com/image.jpg" />

cat > check-social-preview.sh << 'EOF'
#!/usr/bin/env bash
# check-social-preview.sh
# Usage: bash check-social-preview.sh <url>
# Runs a full diagnostic against social preview crawler requirements.
# Tests: OG tags, image size, HTTPS, CSP, X-Content-Type-Options,
#        response time, robots.txt, and crawler accessibility.

set -uo pipefail

TARGET_URL="${1:-}"

if [[ -z "$TARGET_URL" ]]; then
  echo "Usage: bash check-social-preview.sh <url>"
  exit 1
fi

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
BOLD='\033[1m'
RESET='\033[0m'

PASS=0
WARN=0
FAIL=0

pass() { echo -e "  ${GREEN}[PASS]${RESET} $1"; PASS=$(( PASS + 1 )); }
warn() { echo -e "  ${YELLOW}[WARN]${RESET} $1"; WARN=$(( WARN + 1 )); }
fail() { echo -e "  ${RED}[FAIL]${RESET} $1"; FAIL=$(( FAIL + 1 )); }
section() { echo -e "\n${BOLD}${CYAN}--- $1 ---${RESET}"; }

WA_UA="WhatsApp/2.23.24.82 A"
FB_UA="facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)"
LI_UA="LinkedInBot/1.0 (compatible; Mozilla/5.0; Apache-HttpClient +http://www.linkedin.com)"
TW_UA="Twitterbot/1.0"

TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT

echo -e "\n${BOLD}=============================================="
echo -e "  Social Preview Health Check"
echo -e "  $TARGET_URL"
echo -e "==============================================${RESET}\n"

# -------------------------------------------------------
section "1. HTTPS"

if [[ "$TARGET_URL" =~ ^https:// ]]; then
  pass "URL uses HTTPS"
else
  fail "URL uses HTTP. WhatsApp requires HTTPS for previews."
fi

# -------------------------------------------------------
section "2. HTTP Response (WhatsApp UA)"

HTTP_STATUS=$(curl -o /dev/null -s -w "%{http_code}" -A "$WA_UA" -L --max-time 10 "$TARGET_URL" || echo "000")
if [[ "$HTTP_STATUS" == "200" ]]; then
  pass "HTTP 200 OK for WhatsApp user agent"
elif [[ "$HTTP_STATUS" == "301" || "$HTTP_STATUS" == "302" ]]; then
  warn "Redirect ($HTTP_STATUS). Crawler follows redirects but this adds latency."
else
  fail "Non-200 response: $HTTP_STATUS. Crawler may not read page content."
fi

# -------------------------------------------------------
section "3. Response Time"

TOTAL_TIME=$(curl -o /dev/null -s -w "%{time_total}" -A "$WA_UA" -L --max-time 15 "$TARGET_URL" || echo "0")
TTFB=$(curl -o /dev/null -s -w "%{time_starttransfer}" -A "$WA_UA" -L --max-time 15 "$TARGET_URL" || echo "0")
echo "  Total: ${TOTAL_TIME}s  TTFB: ${TTFB}s"

# Convert float to integer milliseconds using awk (no bc dependency)
TOTAL_MS=$(echo "$TOTAL_TIME" | awk '{printf "%d", $1 * 1000}')
if [ "$TOTAL_MS" -lt 3000 ] 2>/dev/null; then
  pass "Response time under 3s"
elif [ "$TOTAL_MS" -lt 5000 ] 2>/dev/null; then
  warn "Response time between 3 and 5s. WhatsApp crawler may timeout."
else
  fail "Response time over 5s. Crawler will likely timeout before reading OG tags."
fi

# -------------------------------------------------------
section "4. Open Graph Tags"

HTML=$(curl -s -A "$WA_UA" -L --max-time 10 "$TARGET_URL" 2>/dev/null || echo "")

check_og_tag() {
  local tag="$1"
  local label="$2"
  local val
  val=$(echo "$HTML" | grep -oiE "property=\"${tag}\"[^>]+content=\"[^\"]+\"" \
    | grep -oiE 'content="[^"]+"' | sed 's/content="//;s/"//' | head -1 || echo "")
  if [[ -z "$val" ]]; then
    val=$(echo "$HTML" | grep -oiE "content=\"[^\"]+\"[^>]+property=\"${tag}\"" \
      | grep -oiE 'content="[^"]+"' | sed 's/content="//;s/"//' | head -1 || echo "")
  fi
  if [[ -n "$val" ]]; then
    pass "${label}: $val" >&2
  else
    fail "${label} missing" >&2
  fi
  echo "$val"
}

OG_TITLE=$(check_og_tag "og:title" "og:title")
OG_DESC=$(check_og_tag "og:description" "og:description")
OG_IMAGE=$(check_og_tag "og:image" "og:image")
OG_URL=$(check_og_tag "og:url" "og:url")
OG_TYPE=$(check_og_tag "og:type" "og:type")

TW_CARD=$(echo "$HTML" | grep -oiE 'name="twitter:card"[^>]+content="[^"]+"' \
  | grep -oiE 'content="[^"]+"' | sed 's/content="//;s/"//' | head -1 || echo "")
TW_IMAGE=$(echo "$HTML" | grep -oiE 'name="twitter:image"[^>]+content="[^"]+"' \
  | grep -oiE 'content="[^"]+"' | sed 's/content="//;s/"//' | head -1 || echo "")

if [[ -n "$TW_CARD" ]]; then
  pass "twitter:card: $TW_CARD"
else
  warn "twitter:card missing. X/Twitter will not render large image cards."
fi

if [[ -n "$TW_IMAGE" ]]; then
  pass "twitter:image: $TW_IMAGE"
else
  warn "twitter:image missing. X/Twitter falls back to og:image, which usually works."
fi

# -------------------------------------------------------
section "5. og:image Analysis"

if [[ -z "$OG_IMAGE" ]]; then
  fail "Cannot analyse og:image because the tag is missing."
else
  IMG_STATUS=$(curl -o /dev/null -s -w "%{http_code}" -A "$WA_UA" -L --max-time 10 "$OG_IMAGE" || echo "000")
  if [[ "$IMG_STATUS" == "200" ]]; then
    pass "og:image URL returns HTTP 200"
  else
    fail "og:image URL returns HTTP $IMG_STATUS. Image is inaccessible to the crawler."
  fi

  if [[ "$OG_IMAGE" =~ ^https:// ]]; then
    pass "og:image uses HTTPS"
  else
    fail "og:image uses HTTP. WhatsApp requires HTTPS images."
  fi

  IMG_CT=$(curl -sI -A "$WA_UA" -L --max-time 10 "$OG_IMAGE" \
    | grep -i "^content-type:" | head -1 | cut -d: -f2- | xargs 2>/dev/null || echo "")
  if [[ "$IMG_CT" =~ image/ ]]; then
    pass "og:image Content-Type: $IMG_CT"
  else
    warn "og:image Content-Type unexpected: '$IMG_CT'. WhatsApp may reject non-image MIME types."
  fi

  IMG_FILE="${TMP}/ogimage"
  curl -s -A "$WA_UA" -L --max-time 15 -o "$IMG_FILE" "$OG_IMAGE" 2>/dev/null || true
  if [[ -f "$IMG_FILE" ]]; then
    SIZE_BYTES=$(wc -c < "$IMG_FILE" | tr -d ' ')
    SIZE_KB=$(echo "$SIZE_BYTES" | awk '{printf "%.1f", $1 / 1024}')
    if [ "$SIZE_BYTES" -gt 307200 ] 2>/dev/null; then
      fail "Image is ${SIZE_KB} KB and exceeds WhatsApp's undocumented ~300 KB limit. This is the most common cause of missing WhatsApp thumbnails."
    elif [ "$SIZE_BYTES" -gt 204800 ] 2>/dev/null; then
      warn "Image is ${SIZE_KB} KB and is approaching the WhatsApp 300 KB limit. Consider optimising."
    else
      pass "Image size: ${SIZE_KB} KB (well within the 300 KB WhatsApp limit)"
    fi

    if command -v identify &>/dev/null; then
      DIMS=$(identify -format '%wx%h' "$IMG_FILE" 2>/dev/null || echo "unknown")
      W=$(echo "$DIMS" | cut -dx -f1 || echo "0")
      H=$(echo "$DIMS" | cut -dx -f2 || echo "0")
      echo "  Image dimensions: ${DIMS}px"
      if [ "$W" -ge 1200 ] && [ "$H" -ge 630 ] 2>/dev/null; then
        pass "Image dimensions meet the 1200x630 minimum recommendation"
      elif [ "$W" -ge 600 ] 2>/dev/null; then
        warn "Image is ${DIMS}px. Minimum 1200x630 is recommended for large card previews."
      else
        fail "Image is ${DIMS}px and is too small for reliable previews on most platforms."
      fi
    else
      warn "ImageMagick not installed so image dimensions could not be checked. Install with: brew install imagemagick"
    fi
  else
    warn "Could not download image for size check"
  fi
fi

# -------------------------------------------------------
section "6. HTTP Security Headers (Crawler Compatibility)"

HEADERS=$(curl -sI -A "$WA_UA" -L --max-time 10 "$TARGET_URL" || echo "")

CSP=$(echo "$HEADERS" | grep -i "^content-security-policy:" | head -1 | cut -d: -f2- || echo "")
if [[ -n "$CSP" ]]; then
  echo "  CSP present: $CSP"
  if echo "$CSP" | grep -qi "img-src"; then
    # Pass if img-src contains https: wildcard or * (allows all HTTPS images)
    if echo "$CSP" | grep -qi "img-src[^;]*https:"; then
      pass "CSP img-src allows all HTTPS images. og:image will be accessible to crawlers."
    elif echo "$CSP" | grep -qi "img-src[^;]* \*"; then
      pass "CSP img-src uses wildcard. og:image will be accessible to crawlers."
    else
      warn "CSP has a restrictive img-src directive. Verify it includes your image CDN domain."
    fi
  else
    pass "CSP does not restrict img-src"
  fi
else
  warn "No Content-Security-Policy header present. Recommended for security, though not required for previews."
fi

XCTO=$(echo "$HEADERS" | grep -i "^x-content-type-options:" | head -1 || echo "")
if [[ -n "$XCTO" ]]; then
  pass "X-Content-Type-Options present: $XCTO"
else
  warn "X-Content-Type-Options missing. Add nosniff for security."
fi

# -------------------------------------------------------
section "7. Crawler Accessibility (Multiple User Agents)"

# check_ua fetches the full HTML body for each crawler UA.
# It passes if HTTP 200 is returned AND og:image is present in the response.
# It notes if Cloudflare Bot Fight Mode has injected a challenge-platform script
# alongside readable OG tags — this is benign cached residue, not an active block.
# It fails if og:image is absent regardless of challenge injection, or if HTTP != 200.
check_ua() {
  local label="$1"
  local ua="$2"
  local tmpfile="${TMP}/ua_$(echo "$label" | tr ' ' '_')"

  local code
  code=$(curl -s -o "$tmpfile" -w "%{http_code}" -A "$ua" -L --max-time 10 "$TARGET_URL" 2>/dev/null || echo "000")

  if [[ "$code" != "200" ]]; then
    fail "$label: HTTP $code. This crawler is being blocked or challenged."
    return
  fi

  local has_og
  has_og=$(grep -oiE 'property="og:image"' "$tmpfile" 2>/dev/null | head -1 || echo "")

  local has_challenge
  has_challenge=$(grep -c "challenge-platform" "$tmpfile" 2>/dev/null || echo "0")

  if [[ -n "$has_og" ]]; then
    if [ "$has_challenge" -gt 0 ] 2>/dev/null; then
      pass "$label: HTTP 200, og:image present. Bot Fight Mode script in HTML but OG tags are readable. WAF Skip rule is working correctly."
    else
      pass "$label: HTTP 200, og:image present. No challenge injection detected."
    fi
  else
    if [ "$has_challenge" -gt 0 ] 2>/dev/null; then
      fail "$label: HTTP 200 but Bot Fight Mode is injecting challenge scripts and og:image is absent. WAF Skip rule is not working for this user agent."
    else
      fail "$label: HTTP 200 but og:image is absent. The page may not be rendering OG tags for this crawler."
    fi
  fi
}

check_ua "WhatsApp UA"          "$WA_UA"
check_ua "facebookexternalhit"  "$FB_UA"
check_ua "LinkedInBot"          "$LI_UA"
check_ua "Twitterbot"           "$TW_UA"

# -------------------------------------------------------
section "8. robots.txt"

BASE_URL=$(echo "$TARGET_URL" | grep -oE '^https?://[^/]+' || echo "")
ROBOTS=$(curl -s --max-time 5 "${BASE_URL}/robots.txt" 2>/dev/null || echo "")

if [[ -z "$ROBOTS" ]]; then
  warn "robots.txt not found or empty"
else
  for bot in facebookexternalhit WhatsApp Facebot LinkedInBot Twitterbot; do
    if echo "$ROBOTS" | grep -qi "User-agent: ${bot}"; then
      if echo "$ROBOTS" | grep -A2 -i "User-agent: ${bot}" | grep -qi "Disallow: /$"; then
        fail "robots.txt blocks $bot. This will prevent all previews from that platform."
      else
        pass "robots.txt references $bot but does not block it."
      fi
    else
      pass "robots.txt has no restrictions for $bot"
    fi
  done
fi

# -------------------------------------------------------
section "9. Cloudflare Detection"

CF_RAY=$(echo "$HEADERS" | grep -i "^cf-ray:" | head -1 || echo "")
CF_CACHE=$(echo "$HEADERS" | grep -i "^cf-cache-status:" | head -1 || echo "")

if [[ -n "$CF_RAY" ]]; then
  echo "  Cloudflare detected: $CF_RAY"
  [[ -n "$CF_CACHE" ]] && echo "  $CF_CACHE"
  pass "Cloudflare is present. If all crawler UA checks above passed, your WAF Skip rule is configured correctly."
else
  pass "No Cloudflare detected. WAF skip rule not required."
fi

# -------------------------------------------------------
echo -e "\n${BOLD}=============================================="
echo -e "  Results Summary"
echo -e "  ${GREEN}PASS: $PASS${RESET}  ${YELLOW}WARN: $WARN${RESET}  ${RED}FAIL: $FAIL${RESET}"
echo -e "==============================================${RESET}\n"

if [ "$FAIL" -gt 0 ]; then
  echo -e "${RED}${BOLD}Action required: $FAIL critical issue(s) found.${RESET}"
elif [ "$WARN" -gt 0 ]; then
  echo -e "${YELLOW}${BOLD}Review warnings: $WARN potential issue(s) found.${RESET}"
else
  echo -e "${GREEN}${BOLD}All checks passed. Social previews should work correctly.${RESET}"
fi
echo 
EOF
chmod +x check-social-preview.sh

==============================================
  Social Preview Health Check
  https://andrewbaker.ninja/2026/03/01/the-silent-killer-in-your-aws-architecture-iops-mismatches/
==============================================

--- 1. HTTPS ---
  [PASS] URL uses HTTPS

--- 2. HTTP Response (WhatsApp UA) ---
  [PASS] HTTP 200 OK for WhatsApp user agent

--- 3. Response Time ---
  Total: 0.247662s  TTFB: 0.155405s
  [PASS] Response time under 3s

--- 4. Open Graph Tags ---
  [PASS] twitter:card: summary_large_image
  [PASS] twitter:image: https://andrewbaker.ninja/wp-content/uploads/2026/03/StorageVsInstanceSize-1200x630.jpg

--- 5. og:image Analysis ---
  [PASS] og:image URL returns HTTP 200
  [PASS] og:image uses HTTPS
  [PASS] og:image Content-Type: image/jpeg
  [PASS] Image size: 127,5 KB (well within the 300 KB WhatsApp limit)
  [WARN] ImageMagick not installed so image dimensions could not be checked. Install with: brew install imagemagick

--- 6. HTTP Security Headers (Crawler Compatibility) ---
  CSP present:  default-src 'self' https: data: 'unsafe-inline' 'unsafe-eval'; img-src 'self' data: https: blob:; font-src 'self' https: data:; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:; style-src 'self' 'unsafe-inline' https:; frame-src 'self' https:; connect-src 'self' https:;
  [PASS] CSP img-src allows all HTTPS images. og:image will be accessible to crawlers.
  [PASS] X-Content-Type-Options present: X-Content-Type-Options: nosniff

--- 7. Crawler Accessibility (Multiple User Agents) ---
  [PASS] WhatsApp UA: HTTP 200, og:image present. Bot Fight Mode script in HTML but OG tags are readable. WAF Skip rule is working correctly.
  [PASS] facebookexternalhit: HTTP 200, og:image present. Bot Fight Mode script in HTML but OG tags are readable. WAF Skip rule is working correctly.
  [PASS] LinkedInBot: HTTP 200, og:image present. Bot Fight Mode script in HTML but OG tags are readable. WAF Skip rule is working correctly.
  [PASS] Twitterbot: HTTP 200, og:image present. Bot Fight Mode script in HTML but OG tags are readable. WAF Skip rule is working correctly.

--- 8. robots.txt ---
  [PASS] robots.txt has no restrictions for facebookexternalhit
  [PASS] robots.txt has no restrictions for WhatsApp
  [PASS] robots.txt has no restrictions for Facebot
  [PASS] robots.txt has no restrictions for LinkedInBot
  [PASS] robots.txt has no restrictions for Twitterbot

--- 9. Cloudflare Detection ---
  Cloudflare detected: CF-RAY: 9d80a8bc4ee8e6de-LIS
  cf-cache-status: HIT
  [PASS] Cloudflare is present. If all crawler UA checks above passed, your WAF Skip rule is configured correctly.

==============================================
  Results Summary
  PASS: 21  WARN: 1  FAIL: 0
==============================================

Review warnings: 1 potential issue(s) found.

convert input.jpg -resize 1200x630 -quality 80 -strip output.jpg
jpegoptim --size=250k --strip-all image.jpg
cwebp -q 80 input.png -o output.webp

Content-Security-Policy: img-src 'self' https://your-cdn-domain.com https://s3.af-south-1.amazonaws.com;

(http.user_agent contains "WhatsApp") or
(http.user_agent contains "facebookexternalhit") or
(http.user_agent contains "Facebot")

cat > audit-wp-og.sh << 'EOF'
#!/usr/bin/env bash
# audit-wp-og.sh
# Usage: bash audit-wp-og.sh audit|fix [post-id]
# Audits WordPress posts for missing og:image via WP-CLI on remote EC2.
#
# Update the four variables below before running.

set -euo pipefail

MODE="${1:-audit}"
SPECIFIC_POST="${2:-}"

EC2_HOST="[email protected]"
SSH_KEY="$HOME/.ssh/your-key.pem"
WP_PATH="/var/www/html"
SITE_URL="https://yoursite.com"

RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
BOLD='\033[1m'
RESET='\033[0m'

echo -e "\n${BOLD}${CYAN}WordPress OG Tag Auditor${RESET}"
echo -e "Mode: ${BOLD}$MODE${RESET}\n"

if [[ "$MODE" == "audit" ]]; then
  echo -e "${YELLOW}Fetching published posts with no featured image...${RESET}\n"

  ssh -i "$SSH_KEY" -o StrictHostKeyChecking=no "$EC2_HOST" bash <<'REMOTE'
echo "Posts with no featured image (og:image will be missing for these):"
wp post list \
  --post_type=post \
  --post_status=publish \
  --fields=ID,post_title,post_date \
  --format=table \
  --meta_query='[{"key":"_thumbnail_id","compare":"NOT EXISTS"}]' \
  --path=/var/www/html \
  --allow-root \
  2>/dev/null || echo "(WP-CLI not available or no posts found)"

echo ""
echo "Total published posts:"
wp post list \
  --post_type=post \
  --post_status=publish \
  --format=count \
  --path=/var/www/html \
  --allow-root \
  2>/dev/null

echo ""
echo "Posts with featured image set:"
wp post list \
  --post_type=post \
  --post_status=publish \
  --format=count \
  --meta_key=_thumbnail_id \
  --path=/var/www/html \
  --allow-root \
  2>/dev/null
REMOTE

  echo -e "\n${YELLOW}Spot-checking live og:image tags on recent posts...${RESET}\n"
  WA_UA="WhatsApp/2.23.24.82 A"
  URLS=$(curl -s "${SITE_URL}/post-sitemap.xml" \
    | grep -oE '<loc>[^<]+</loc>' \
    | sed 's|<loc>||;s|</loc>||' \
    | head -10)

  if [[ -z "$URLS" ]]; then
    echo -e "${YELLOW}Could not fetch sitemap at ${SITE_URL}/post-sitemap.xml${RESET}"
  else
    printf "%-70s %s\n" "URL" "og:image"
    printf "%-70s %s\n" "---" "--------"
    while IFS= read -r url; do
      html=$(curl -s -A "$WA_UA" -L --max-time 8 "$url" 2>/dev/null)
      og_img=$(echo "$html" \
        | grep -oiE 'property="og:image"[^>]+content="[^"]+"' \
        | grep -oiE 'content="[^"]+"' \
        | sed 's/content="//;s/"//' \
        | head -1)
      if [[ -n "$og_img" ]]; then
        printf "%-70s ${GREEN}%s${RESET}\n" "$(echo "$url" | sed "s|${SITE_URL}||")" "PRESENT"
      else
        printf "%-70s ${RED}%s${RESET}\n" "$(echo "$url" | sed "s|${SITE_URL}||")" "MISSING"
      fi
    done <<< "$URLS"
  fi

elif [[ "$MODE" == "fix" ]]; then
  if [[ -z "$SPECIFIC_POST" ]]; then
    echo -e "${RED}Provide a post ID: bash audit-wp-og.sh fix <post-id>${RESET}"
    exit 1
  fi

  ssh -i "$SSH_KEY" -o StrictHostKeyChecking=no "$EC2_HOST" bash <<REMOTE
echo "Available media attachments (most recent 10):"
wp post list \
  --post_type=attachment \
  --posts_per_page=10 \
  --fields=ID,post_title,guid \
  --format=table \
  --path=$WP_PATH \
  --allow-root \
  2>/dev/null
REMOTE

  echo -e "\n${YELLOW}To assign a featured image to post $SPECIFIC_POST:${RESET}"
  echo "  ssh -i $SSH_KEY $EC2_HOST \\"
  echo "    wp post meta set $SPECIFIC_POST _thumbnail_id <ATTACHMENT_ID> --path=$WP_PATH --allow-root"
  echo ""
  echo "Then retest: bash diagnose-social-preview.sh ${SITE_URL}/?p=${SPECIFIC_POST}"

else
  echo -e "${RED}Unknown mode: $MODE. Use 'audit' or 'fix'.${RESET}"
  exit 1
fi
EOF

chmod +x audit-wp-og.sh
echo "Written and made executable: audit-wp-og.sh"