Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chartcastr.com/llms.txt

Use this file to discover all available pages before exploring further.

Private Beta — WhatsApp delivery is in private beta. Contact us for access.

​
Overview

Push a chart image, a short AI-written read of what changed, and a deeper analysis as a threaded follow-up — straight to a WhatsApp number on your team’s schedule. Built on the official WhatsApp Business Cloud API (no third-party bots).

​
Features

  • Image + caption delivery — chart is sent as a native WhatsApp image with a *bold title*, AI short summary, and up to two highlights as the caption (1024 char cap).
  • Threaded AI analysis — the long-form analysis is sent as a follow-up reply (context.message_id) so it renders as a thread to the chart.
  • Two-way thread — replies and emoji reactions on the chart message trigger an AI follow-up, posted back in the same conversation.
  • Per-message delivery status — sent / delivered / read / failed callbacks are persisted on the pulse for support visibility.
  • No third-party bots — uses Meta’s first-party Cloud API.

​
Setup (one-time, Meta side)

You’ll need a Meta Business app with the WhatsApp product enabled. The shortest path:
1

Create (or reuse) a Meta App

Go to developers.facebook.com/apps → Create App → type Business. If you already host Meta Ads inside an app, you can re-use it, but separate apps are recommended (Meta reviews whatsapp_business_messaging independently from ads_management).
2

Add the WhatsApp product

From your app’s dashboard, Products → Add product → WhatsApp → Set up. Meta will provision a test phone number for free.
3

Create a System User (for the permanent token)

business.facebook.com → Settings → Users → System Users → Add → Admin role. Assign the WhatsApp asset and your app to this System User.Then click Generate New Token → pick your app → select the scopes:
  • whatsapp_business_messaging
  • whatsapp_business_management
  • business_management
Copy the token (it starts with EAAB...) — this is the System User Access Token you’ll paste into Chartcastr. It’s permanent unless you revoke it.
4

Note the Phone Number ID + WhatsApp Business Account ID

In the WhatsApp product page, API Setup lists the test phone number, its Phone number ID (a 15-digit number), and the WhatsApp Business Account ID (WABA ID).
5

Add allowed recipients (test mode only)

Until your app is reviewed, you can only send to numbers added under API Setup → To (max 5). Add your own phone first so you can send yourself test pulses.
6

Configure the webhook

Still under WhatsApp → Configuration → Webhook:
  • Callback URL: https://api.chartcastr.com/webhook/integrations/whatsapp
  • Verify Token: any random string you choose — save it as the env var META_WHATSAPP_WEBHOOK_VERIFY_TOKEN on the Chartcastr server.
  • Subscribe to the messages field on the WABA.
Meta will GET the URL with hub.challenge to verify. Chartcastr replies with the challenge automatically.
7

Connect inside Chartcastr

In Chartcastr → Settings → Destinations → WhatsApp → Connect and paste:
  • System User Access Token
  • Phone Number ID
  • Display Phone Number (the human-readable form, e.g. +1 555 123 4567)
  • WABA ID
8

Send your first pulse

Create a connection from any data source (Google Sheets, HubSpot, etc.) → pick WhatsApp: Send to a phone number → enter your phone number. The first pulse fires immediately as a test.

​
The 24-hour window rule

Meta only allows free-form business-initiated messages within 24 hours of the recipient’s last inbound message. The first time you message a brand-new recipient:
  • If they have messaged your business in the last 24 hours → free-form delivery works (this is what Chartcastr does today).
  • Otherwise → Meta requires an approved Message Template (e.g. a “weekly update” utility template).
If your first scheduled pulse fails with error.code: 131051 or 131047, the recipient is outside the window. Have them text your WhatsApp business number once (anything works — “hi”) to open the window, then re-run the pulse.
Template-message support is on the roadmap. Until then, schedule pulses for recipients who already have an open conversation with your business number.

​
Architecture

┌──────────────┐ chart.png + AI summary ┌────────────────────┐
│  Chartcastr  │ ─────────────────────▶│  WhatsApp Cloud    │
│  Pulse Run   │  POST /messages       │  API (graph.fb)    │
└──────────────┘                       └────────────────────┘
       ▲                                          │
       │ X-Hub-Signature-256                       │ wamid.*
       │ POST /webhook/integrations/whatsapp       ▼
       └────── inbound reply / reaction ── recipient phone
  • Outbound: image is uploaded to /{phoneNumberId}/media → media ID is sent in an image message with caption → long analysis is sent as a text message with context.message_id referencing the image’s wamid.
  • Inbound: Meta POSTs the user’s reply to /webhook/integrations/whatsapp. The handler verifies the HMAC, looks up the originating pulse by context.id (matched against ExternalContextThread.externalMessageId), runs the AI follow-up engine, and posts the response back.

​
Supported sources

WhatsApp works with every Chartcastr data source.

Google Sheets

Send live KPIs to a co-founder’s phone every morning.

Shopify

Daily revenue snapshots to your phone.

HubSpot

Pipeline health pulses to the CRO.

Linear

Weekly velocity to the engineering lead.

​
Limits and gotchas

  • Caption is capped at 1024 chars (Chartcastr trims with …).
  • Text body (analysis) is capped at 4096 chars.
  • Rate limits: tier-based, starting at 1k unique recipients / 24h for an unverified business. Watch the WABA quality rating.
  • Reactions arrive as type: reaction events — Chartcastr treats them like a one-character reply.
  • Group chats are not supported by the Cloud API (only 1:1 conversations). Group delivery is on the long-term roadmap once Meta GA’s the WhatsApp Groups API.

​
Troubleshooting

SymptomLikely cause
error.code: 131051 or 131047Recipient is outside the 24-hour window. Have them message your business number, or use a template.
error.code: 190 (token expired)The System User token was revoked or expired. Re-generate it in Business Manager and update Chartcastr.
Webhook never firesSubscribe the messages field on the WABA in Configuration, not just on the app.
Image fails to sendMake sure the chart URL is reachable; we fall back to image.link only when the in-app media upload fails.

​
Next Steps