Loading components
Messaging (Photon)
Receive iMessage, SMS, WhatsApp, Email, and Telegram messages via Photon webhooks in Convex with durable storage, deduplication, and an outbox with retries.
Installation
npm install @photon-ai/convexAbout Messaging (Photon)
This component connects Convex to Photon's messaging API: your app receives iMessage, SMS, WhatsApp, Email and Telegram messages from a Photon webhook and sends replies through the Photon API. Every delivery is verified, and each new message is stored, deduplicated by message id, before the webhook returns 200. Convex's scheduler then runs your handler, and an outbox sends its replies with retries.
Benefits
- Acknowledge Photon webhook deliveries durably before returning 200, so no message is lost between receipt and processing.
- Deduplicate at-least-once deliveries automatically using message IDs, preventing double-handling without any application code.
- Handle reply bursts with collapse mode, which cancels in-flight turns when a newer message arrives and carries prior messages forward as context.
- Send replies through the Photon API from Convex's default runtime with built-in idempotent retries, no Node.js action required.
Use cases
how to receive WhatsApp and iMessage webhooks in Convex
The @photon-ai/convex component registers a POST /photon/webhook HTTP route in your Convex deployment. Photon delivers incoming messages from iMessage, SMS, WhatsApp Business, Email, and Telegram to that endpoint, where the component verifies the signature and writes the message to a Convex table before returning 200. Your onTurn handler is then scheduled via Convex's scheduler.
how to build an LLM chatbot that replies to SMS and WhatsApp with Convex
Use @photon-ai/convex with mode set to 'collapse' so that bursts of messages are merged into a single turn, reducing redundant LLM calls. Your onTurn handler receives a messages array and a carried array of prior messages from cancelled turns. After generating a reply, call photon.sendMessage to queue it through the Photon API with automatic retries.
deduplicate Photon webhook message deliveries in Convex
The @photon-ai/convex component deduplicates incoming messages on message ID at the HTTP action layer before the 200 response is sent. Because the write happens inside the same transaction that acknowledges the webhook, a redelivered message is stored exactly once regardless of how many times Photon retries the delivery.
retry failed message sends to Photon API from Convex
The component maintains an outbox table in Convex and sends each reply through the Photon API with a single idempotency key across retries. It retries on network errors and 408, 429, or 5xx responses with delays of 4s, 16s, 64s, and 256s. Terminal errors such as 409 SPACE_NOT_SENDABLE are recorded in the outbox row without further retries.
Frequently asked questions
What messaging platforms does @photon-ai/convex support?
@photon-ai/convex supports receiving messages from iMessage, SMS, WhatsApp Business, Email, and Telegram through the Photon Beta platform. Incoming messages from all these platforms are delivered to a single Convex webhook endpoint and processed through the same pipeline.
What is the difference between immediate mode and collapse mode?
In immediate mode (the default), every received message triggers its own independent handler call, so N messages produce N handler invocations. In collapse mode, a new message supersedes any in-flight turn, cancels replies that have not yet been sent, and passes all messages forward as context in the next turn. Collapse mode is recommended when replies involve expensive operations like LLM calls.
How does @photon-ai/convex prevent duplicate replies when a Convex action is retried?
@photon-ai/convex assigns each outbox row a single idempotency key that is sent as the idempotency-key HTTP header on every attempt to the Photon API. If a retry occurs after a lost response, Photon returns the original result instead of sending the message again. This guarantee applies to both sendMessage and markMessageRead calls.
Do I need a Node.js action to send messages through the Photon API?
No. @photon-ai/convex sends replies through the Photon API from Convex's default V8 runtime without requiring a 'use node' action. Credentials are stored in the component's config table and passed with every request by PhotonComponent.
How do I configure the Photon webhook secret and API key for @photon-ai/convex?
Set the environment variables PHOTON_PROJECT_ID, PHOTON_API_KEY, PHOTON_WEBHOOK_SECRET, and optionally PHOTON_BASE_URL in your Convex deployment dashboard. Alternatively, pass projectId, apiKey, webhookSecret, and baseUrl directly to the PhotonComponent constructor. The webhook signing secret is used to verify every incoming delivery and the request is rejected with 401 if verification fails.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.