Assembly LineDocs

Photon iMessage Channel

Photon/Spectrum channel setup, delivery modes, ingress auth, typing lifecycle, rich tools, and file handling.

Edit

@assemblyline-agents/photon connects an agent to iMessage through Photon/Spectrum. It keeps Photon at the channel boundary: inbound webhooks are normalized into Assembly Line turns, and outbound side effects go through a Photon transport, either Photon's Spectrum cloud directly, or a bridge you host.

Photon webhooks are at-least-once. The adapter returns a fast 2xx accepted response and uses X-Spectrum-Webhook-Id + message.id as the default idempotency key, falling back to message.id when the webhook id header is absent.

Delivery Modes

The adapter picks the outbound transport from the environment at send time:

ModeSelected whenRequired env
Direct (Spectrum cloud)No transport URL is set and both project credentials are setPHOTON_PROJECT_ID, PHOTON_PROJECT_SECRET
Bridge (self-hosted)PHOTON_TRANSPORT_URL (or PHOTON_BRIDGE_URL) is setPHOTON_TRANSPORT_URL, PHOTON_BRIDGE_TOKEN

Direct talks to Photon's Spectrum cloud with the project's credentials and requires no bridge. It loads spectrum-ts dynamically from the agent's dependencies, so bridge-only agents do not need that package. Direct mode supports text and Markdown, media by URL, typing, app cards, backgrounds, and DM destinations. Reactions and polls depend on the installed spectrum-ts version. The adapter skips unsupported reactions and tells you to configure a bridge for unsupported polls. Inbound attachment downloads always require a bridge; see Inbound Files.

Bridge posts every side effect to a transport bridge you host (see Outbound Bridge Contract), authenticated with Authorization: Bearer <PHOTON_BRIDGE_TOKEN>. When a transport URL is set without a token, sends fail with PHOTON_BRIDGE_TOKEN is required for Photon delivery.; when neither mode is configured, sends fail with PHOTON_TRANSPORT_URL is required for Photon delivery (or set PHOTON_PROJECT_ID/PHOTON_PROJECT_SECRET for direct delivery).

One-Line Channel Setup

Create channels/photon.ts in an agent folder. definePhotonChannel() provides inbound normalization, the typing lifecycle, and outbound delivery:

import { definePhotonChannel } from "@assemblyline-agents/photon";

export default definePhotonChannel();

This compiles to an HTTP channel on /photon/events. The helper stamps the ingress-auth requirement but no transport environment requirement. It resolves the delivery mode at send time, so the same channel file works in both modes. Pass options to override the route, methods, or description: definePhotonChannel({ route: "/imessage" }).

Manual Wiring

If you prefer to wire the handlers by hand (for example, to wrap one of them), re-export them explicitly instead of using the helper:

import { defineChannel } from "@assemblyline-agents/core";
import {
  normalizeHttp as normalizePhotonHttp,
  send as sendPhoton,
  startTurn as startPhotonTurn
} from "@assemblyline-agents/photon";

export default defineChannel({ transport: "http", route: "/photon/events", methods: ["POST"] });
// Bridge mode only: pin the transport env at preflight. Omit for direct mode.
export const requiredEnv = ["PHOTON_TRANSPORT_URL", "PHOTON_BRIDGE_TOKEN"];
export const normalizeHttp = normalizePhotonHttp;
export const startTurn = startPhotonTurn;
export const send = sendPhoton;

Named exports take precedence over the default export's handlers. The explicit requiredEnv line pins the channel to bridge mode during preflight; definePhotonChannel() itself stamps no requiredEnv, so leave it out when the agent may run with direct delivery.

If manual wiring omits startTurn, the compiler emits photon-channel-missing-typing and the runtime records channel.turn_lifecycle_unsupported. The definePhotonChannel() form always wires typing.

Ingress Auth

Set PHOTON_WEBHOOK_SIGNING_SECRET to verify X-Spectrum-Signature (HMAC-SHA256 over v0:<timestamp>:<body>, with a configurable timestamp tolerance). Alternatively set PHOTON_INGRESS_TOKEN and have the sender pass Authorization: Bearer <token>. Unsigned Photon ingress is local/dev-only; production runtime boot rejects a Photon channel when neither a signing secret nor bearer token is configured.

The production boot check accepts exactly PHOTON_WEBHOOK_SIGNING_SECRET or PHOTON_INGRESS_TOKEN; the aliases PHOTON_SIGNING_SECRET and PHOTON_WEBHOOK_BEARER_TOKEN satisfy per-request verification but not the boot check, so always set at least one canonical name in production.

Typing Lifecycle

For fast-ack HTTP ingress, the runtime starts the typing lifecycle after capacity admission and idempotency reservation. It does this while runtime initialization and durable run creation continue. Rejected turns and idempotent replays do not start a duplicate indicator. Direct runtime calls start the lifecycle during run setup. Both paths start typing before attachment intake and model work, then stop it immediately before delivery. definePhotonChannel() maps this lifecycle to Photon typing signals.

The indicator is refreshed every PHOTON_TYPING_REFRESH_MS (default 4 seconds). In bridge mode, typing signals are posted to /v1/messages/interact with action: "typing" and state: "start" | "stop"; in direct mode they map onto the Spectrum typing API. Typing failures are logged as warnings and never fail the run, and when no transport or destination is available the lifecycle is a no-op.

Markdown Replies

Photon's Spectrum bridge renders full CommonMark in iMessage, so the adapter sends replies as textFormat: "markdown" whenever the response contains renderable markdown, headings, lists, tables, fenced or inline code, blockquotes, links, or bold/italic. Plain casual messages (no markdown syntax) are sent as plain so they read like a normal text, with casual sentence-ending punctuation softened.

You can override the detection per delivery with a textFormat field on the delivery payload, or call photonTextForReply(body, "markdown") directly.

Rich Feature Tools

Drop these tool factories into the agent's tools/ folder to let the agent send rich Photon side effects to the current conversation. Each resolves the transport and reply destination from the run's channel context, so the model only supplies the content:

// tools/photon_react.ts
import { definePhotonReactionTool } from "@assemblyline-agents/photon";
export default definePhotonReactionTool();

Available factories:

  • definePhotonReactionTool: tapback the user's latest message (like, love, laugh, emphasize, dislike, question)
  • definePhotonPollTool: send a native iMessage poll (title + 2–10 options)
  • definePhotonAppCardTool: send a styled link card (caption, subcaption, image)
  • definePhotonBackgroundTool: set or clear the chat background image

Each factory accepts { description?, needsApproval? } to customize the model-facing description or gate the side effect behind an approval. In direct mode, reactions and polls depend on the installed spectrum-ts version (see Delivery Modes).

Outbound Bridge Contract

In bridge mode, the adapter expects PHOTON_TRANSPORT_URL to point at a bridge exposing the Photon transport endpoints:

  • POST /v1/messages/send: final replies: text or markdown body, native reply targets, link previews, and optional media fields
  • POST /v1/messages/interact: reactions (action: "react") and typing signals (action: "typing", state: "start" | "stop")
  • POST /v1/messages/poll
  • POST /v1/messages/app
  • POST /v1/messages/background

The direct transport additionally routes a dedicated /v1/messages/typing path ({ "action": "start" | "stop" }) for hosts that address typing explicitly; bridges only receive typing through /v1/messages/interact.

Optional media fields on a send:

{
  "mediaUrl": "https://example.com/image.png",
  "mediaFilename": "image.png",
  "mediaMimeType": "image/png"
}

Every request carries an idempotency key. Bridge responses are parsed as JSON and read up to a fixed 512 KiB cap; non-2xx responses raise Photon transport returned HTTP <status>: <payload>.

Inbound Files

Photon attachment content is preserved as runtime-visible files, not just message metadata. When Spectrum sends attachment content with fields such as name, mimeType, size, and downloadUrl/contentUrl/url. The adapter keeps those references in ChannelTurn.attachments. The runtime then downloads the bytes after the webhook ACK, stores them through the configured blob adapter, and exposes them under /files/original/... with entries in /files/manifest.json. Attachment downloads are restricted to the PHOTON_TRANSPORT_URL origin, which is why inbound files require a bridge even when outbound delivery runs in direct mode.

Photon bridge multipart/form-data forwarding is also supported. When the bridge sends asset_manifest_json plus matching file parts. The Node host parses the file bytes and the Photon adapter converts them into inline attachments before runtime storage. Prefer form forwarding for uploaded files; JSON forwarding can describe attachments, but it cannot carry the actual file bytes unless it includes an explicit downloadable URL.

Markdown/text uploads read back as UTF-8 through read; binary uploads remain byte-accurate when hydrated under /files. ZIP uploads are kept as their original archive under /files/original/... and, when extraction succeeds, safe entries are also exposed under /files/extracted/<archive-name>/... so the agent can open and project files from a zipped folder directly. If the download URL points at the Photon bridge origin. The runtime uses PHOTON_BRIDGE_TOKEN for the fetch without exposing that token to the model context.

Environment Reference

PHOTON_* variables are canonical on this page; runtime-wide ASSEMBLY_LINE_* variables live in the Configuration Reference.

VariableValuesDefaultEffect
PHOTON_TRANSPORT_URLURLunsetBridge base URL; presence selects bridge mode. PHOTON_BRIDGE_URL is an accepted alias.
PHOTON_BRIDGE_TOKENstringunsetBearer token for bridge requests and bridge-origin attachment downloads; required in bridge mode.
PHOTON_PROJECT_IDstringunsetSpectrum project id for direct delivery.
PHOTON_PROJECT_SECRETstringunsetSpectrum project secret for direct delivery.
PHOTON_WEBHOOK_SIGNING_SECRETstringunsetHMAC secret for X-Spectrum-Signature verification. Alias: PHOTON_SIGNING_SECRET (request verification only, not the production boot check).
PHOTON_INGRESS_TOKENstringunsetExpected webhook Authorization: Bearer token. Alias: PHOTON_WEBHOOK_BEARER_TOKEN (request verification only, not the production boot check).
PHOTON_WEBHOOK_TOLERANCE_SECONDSinteger, 30–86400300Maximum accepted signature timestamp age.
PHOTON_SEND_REQUEST_TIMEOUT_MSinteger, 1000–12000030000Timeout for sends, polls, app cards, and backgrounds.
PHOTON_TYPING_REQUEST_TIMEOUT_MSinteger, 500–150003000Timeout for typing and reaction requests.
PHOTON_TYPING_REFRESH_MSinteger, 1000–300004000Typing indicator refresh cadence.

Exports

@assemblyline-agents/photon exports, grouped by concern:

  • Channel: definePhotonChannel, normalizeHttp, startTurn, send, resolveAttachment
  • Transport helpers: sendPhotonReply, sendPhotonReaction, sendPhotonPoll, sendPhotonAppCard, sendPhotonBackground, startPhotonTyping
  • Text formatting: photonTextForReply, photonTextFormatForReply, shouldSendPhotonMarkdown, containsRenderableMarkdown, softenIMessageBubbleEndings
  • Tools: definePhotonReactionTool, definePhotonPollTool, definePhotonAppCardTool, definePhotonBackgroundTool, photonTransportFromToolContext, photonDestinationFromToolContext
  • Mode and env constants: directPhotonEnabled, PHOTON_REQUIRED_ENV, PHOTON_DIRECT_ENV, PHOTON_WEBHOOK_ENV, PHOTON_INGRESS_SECRET_ENV

Adapters

Choose interchangeable runtime, state, storage, deployment, channel, and sandbox providers.

Authoring Plugins

Implement provider, connection, channel, and skill contributions and publish them as Assembly Line plugin packages.

On this page

Delivery ModesOne-Line Channel SetupManual WiringIngress AuthTyping LifecycleMarkdown RepliesRich Feature ToolsOutbound Bridge ContractInbound FilesEnvironment ReferenceExportsRelated Docs