Photon

Get the Photon account the connection acts as: id, email, name, phone. Needs an Account Service Key; a project key is refused.

Get the organization this connection acts in — the one a sign-in with Photon was approved for — with the organizationId list_projects needs. Not in Photon's published API document; Photon support confirmed it (needs organization:read).

Change the account's first or last name (lastName null clears it). Needs an Account Service Key.

List the OAuth applications authorized on the account. Needs an Account Service Key.

Revoke one OAuth application's grant on the account (application.id, connect_app_…). Needs an Account Service Key.

List the account's Account Service Keys — names, ids, expiry — never their secrets. Create or revoke them in Photon's dashboard or CLI.

Read an organization's billing subscription, charges and entitlements.

List an organization's invoices (zero-total invoices are left out).

Whether the organization has a card on file, and its non-secret details.

Get a hosted URL where a person adds a payment card for the organization. Hand the URL to a human; check get_organization_payment_method afterwards.

List Photon's plan catalog (the same for every project): categories, plan codes and what they include. Use it to choose change_plan's category and planCode.

A project's plans, entitlements and current-period usage.

Poll a plan change (change_plan answers an operation id, pho_bop_…) until it succeeds or fails.

Purchase or change a project's plan for one category (e.g. messaging → a planCode from list_billing_plans). Charges the organization's card on file. Usually answers 202 with a billing operation to poll with get_billing_operation.

Schedule a project's billing category to stop at the end of its current period; it stays active until cancelsAt.

Remove a scheduled cancellation so the category renews normally.

List an organization's active projects, newest first; filter by name text and creation window; page with pageToken. Needs an Account Service Key.

Count the projects list_projects would return for the same filters.

Whether create_project would accept this slug right now (advisory: the create itself allocates).

Create a project in an organization. The slug (3–63 lowercase alphanumerics and single hyphens) is permanent. Needs an Account Service Key.

Progress of a project deletion (delete_project): per-domain progress and whether closure is complete.

Get a project: name, slug, organization, agent profile. With no projectId, the connection's own project — the way to learn its organizationId.

Rename a project (the slug cannot change). Needs an Account Service Key.

Start deleting a project and everything in it — its lines, numbers, messages and keys. Follow with get_project_closure_status. Needs an Account Service Key; a connection whose own project this is stops working.

The project's agent profile: the name and avatar recipients see.

Change the agent's first or last name (lastName null clears it).

Start an avatar change: a ten-minute presigned S3 POST (uploadUrl + formFields) for a JPEG, PNG or WebP up to 5 MiB. Upload the file there without Photon credentials, then commit_agent_avatar with the uploadId.

Make an uploaded image (create_agent_avatar_upload's uploadId) the agent's avatar.

Replace the agent's avatar with Photon's default planet image; the custom avatar is discarded.

List a project's API keys — names, permissions, expiry — never their secrets. Create, change or revoke them in Photon's dashboard or CLI. Needs an Account Service Key.

Send into a conversation (Space) as one of the project's agents: a text (plain or markdown), an uploaded attachment or voice note, a reaction to a message (parentMessageId), a poll or a vote on one, a read receipt, a typing update, a DTMF digit on a call, or a group of such parts. SMS, email, WhatsApp, WhatsApp Business and dedicated iMessage lines; email takes to/cc/bcc/subject. Answers 202: the Message with status accepted, then delivered or failed (get_message). Edits, unsends, poll changes and participant changes are their own tools.

Edit the text of a message this agent sent, where the platform supports edits (iMessage, WhatsApp). Answers 202 with the edit as a Message.

Unsend (delete) a message this agent sent, for everyone where the platform supports it. reason and scope are Photon's optional notes on the deletion.

Take back a reaction this agent added to a message.

Change a poll this agent sent: its question, options or selection mode (the whole poll is restated).

Add or remove participants of a group conversation. Pass the User records get_user returns; their timestamps are dropped, as Photon's snapshot shape requires. At least one of added or removed.

List a project's messages, newest first: filter by line (resourceId), conversation, user perspective, direction, platform and time; page with pageToken (at most 200 a page). Eventually consistent.

Count messages matching list_messages' filters; groupBy direction and/or perspectiveUser, or interval=day for daily buckets in a timeZone.

Get one message by id: content, sender, space, status (received, accepted, dispatched, delivered, failed) and timestamps.

Send a read receipt for an incoming message from its receiving line. Answers 202 with the action Message that tracks the outcome.

List conversations: filter by platform, participant (id or phone/email handle), time, or by a message they contain; order by last_message_created_at for most recent activity. At most 100 a page.

Count conversations matching list_spaces' filters; groupBy messagePerspectiveUser splits by the user on the messages (needs messageResourceId).

Get one conversation: platform, kind (direct or group), participants and details.

Open (or find) a conversation between Users: iMessage and WhatsApp take exactly 2 participants, SMS 2–9, email 1–51; one must be a project agent. Direct Spaces converge by participants; each call opens a new email thread. Answers the Space.

Show or stop a typing indicator in a conversation as an agent (true refreshes; repeat to keep it showing). Answers 202 with the dispatched Message.

List the people and agents the project knows: filter by platform, time, or by a message they sent or received; or read up to 100 by userIds in one call.

Count Users matching list_users' filters.

Get one User with a refreshed classification: Human or Agent, handle, platform, and for agents which line (resourceId) they are.

Resolve a handle (an E.164 phone number, an email address, an iMessage address) on a platform to a User, creating it if new. The first step before create_space with someone new.

List uploaded attachments: id, filename, content type, size. The bytes come from download_attachment.

One attachment's metadata.

The platform types this project can use (sms, email, whatsapp, whatsapp_business, imessage, …).

Whether the project is on shared or dedicated iMessage lines, with the shared seat cap.

Whether the project is on shared or dedicated WhatsApp lines, with the shared seat cap.

List everything the project holds — SMS numbers, dedicated lines, WhatsApp senders — oldest first, with each one's abilities (sms, imessage, whatsapp, pstn_voice, …) and state. Filter by type, ability or comma-separated states. In-flight provisions are operations, not resources.

One line or number: abilities, state and its public detail (the phone number, health).

Give a resource back: an SMS number is retired, a dedicated line returns to the pool; its charge period closes. Usually immediate (200), sometimes an operation to poll (202).

List the project's provisioning and release operations, oldest first, running ones included; filter by resourceId, comma-separated states or one type.

Poll one operation until its state is succeeded, failed or cancelled; a finished provision carries the resource, an email domain's detail carries its DNS records.

Withdraw a provision that has not been fulfilled — a dedicated line still waiting for inventory, an SMS number before its provider order. Campaign operations cannot be cancelled.

List who holds a seat on the project's shared iMessage lines (released seats only with includeReleased).

Give an end user a seat on a shared iMessage line: their handle (E.164 phone or email) is mapped onto a pooled number the server picks. An email invites them.

One shared iMessage line assignment.

Free a shared iMessage seat and its handle; the row stays for audit with releasedAt set, so repeating is safe.

Claim a dedicated iMessage line for the project. Always an operation (202): capacity can take hours, so poll get_operation or cancel_operation to stop waiting. Needs the dedicated-lines entitlement; billed once a line is claimed.

Remove iMessage from a dedicated line (the number and any WhatsApp on it stay). Usually immediate, sometimes an operation to poll.

List who holds a seat on the project's shared WhatsApp lines.

Give an end user's phone number a seat on a shared WhatsApp line; an email invites them.

One shared WhatsApp line assignment.

Free a shared WhatsApp seat; repeating is safe.

Provision a dedicated WhatsApp line (with shared Voice), on the project's iMessage line when possible so both keep one number. Always an operation (202) to poll or cancel.

Remove WhatsApp from a dedicated line (iMessage and the number stay).

The WhatsApp Business Account connected to the project: business, review status, outbound capacity, sender count.

The connected WABA's phone numbers straight from Meta, with whether each is in Photon's inventory.

What a browser needs to open Meta's Embedded Signup popup for this project: configId, graphVersion and scopes.

Finish Embedded Signup: exchange the code, WABA id and phone-number id the popup returned and connect that number as a whatsapp_sender. Free, but the organization needs a card on file. Answers an operation.

Register one of the project's own SMS-capable VoIP lines as a WhatsApp Business sender; Photon handles the SMS ownership code. Answers an operation.

Read the latest WhatsApp Business ownership code Meta texted to one of the project's VoIP numbers, if newer than receivedAfter (within the last two minutes). A missing code is a retryable 404.

Disconnect every WhatsApp Business sender and the account itself from the project (the numbers stay in Meta and Photon). Answers an operation to poll.

Countries SMS numbers can be bought in.

US area codes with current provider coverage for new numbers.

Buy one US local number (optionally in an area code from list_sms_area_codes) as an SMS-enabled resource. Always an operation (202): poll get_operation, cancel_operation while it waits for inventory. Billed on delivery.

An SMS line's 10DLC campaign assignment, its eligibility and the version assign_sms_campaign needs.

Attach (or replace) a ready 10DLC campaign from the organization on an SMS line; needs the current expectedVersion from get_sms_campaign. Provider provisioning runs as an operation.

Detach an SMS line's 10DLC campaign (number and campaign stay owned); needs the current expectedVersion.

Start connecting a managed Telegram bot: the answer is an operation whose detail.setupUrl a person opens to pick or create the bot; then poll get_operation.

Connect a sending domain: Photon starts provider setup and the operation's detail lists the DNS records to publish; poll get_operation until the domain is READY.

The project's Voice (SIP routing) profiles; default=true for the project default only.

Create an additional Voice profile (the project default must already exist).

The project's default Voice profile, with its inbound and outbound state.

Create the project's default Voice profile when it has none (an identical replay returns the existing one).

Change the default profile's protocol or media encryption; needs its current expectedVersion.

One Voice profile, with its inbound and outbound state.

Rename an additional profile or change its protocol or media encryption; needs its current expectedVersion.

Delete an additional Voice profile (never the default); force=true also drops the line overrides pointing at it.

Point a profile's inbound calls at a SIP destination URI (sip: or sips:). Destination authentication is left as it is; set a username and password in Photon's dashboard.

Remove a profile's inbound destination (the profile and its lines stay).

Switch a profile's outbound SIP Digest algorithm (sha-256 recommended, md5 legacy); the credential itself is unchanged.

Revoke a profile's outbound calling credential (inbound and lines stay).

Which Voice profile a line overrides to; a line on the project default answers without profileId.

Route one line's calls to an additional profile instead of the default; needs the line's current expectedVersion.

Send a line back to the project's default Voice profile.

Atomically set or clear (profileId null) the profile override on up to 100 lines; every expectedVersion must match or nothing changes.

The message_events SQL schema, dialect, capabilities and limits query_metrics accepts.

Run read-only SQL over the project's message_events table (delivery outcomes, volumes, latency by platform); get_metrics_schema lists the columns. parameters bind named placeholders.

Progress of the historical metrics backfill (queries work meanwhile).

The published webhook payload versions (calendar dates) and which are selectable for new destinations.

The event types a payload version offers (message.created, message.updated, …), with descriptions and schema links.

The JSON Schema of one event type in one payload version.

The IP addresses Photon delivers webhooks from, for a receiver's allowlist.

The project's webhook destinations (never their signing secrets).

Register an HTTPS URL to receive events of a payload version. The answer carries the signing secret once — keep it for verifying webhook-signature headers (Standard Webhooks).

One webhook destination's configuration.

Change a destination's URL, name, description (null clears), events or status (disable to pause delivery). The payload version cannot change.

Delete a webhook destination (repeating is safe).

Issue a destination a new signing secret (returned once); the old one keeps verifying for overlapSeconds (default a day).

Wake a waiting (backed-off) delivery for an immediate attempt; expectedAttemptCount fences stale requests. Answers 202: an attempt, not a success.

Read an attachment's bytes (up to 2 MiB): an image comes back as an image, audio as audio, text or JSON as text, anything else as an embedded blob. A just-uploaded attachment may answer 409 ATTACHMENT_NOT_READY with a Retry-After.

Upload a file (base64, up to 10 MiB) as a project attachment and get its pho_att_… id, to send with send_message as an attachment or voice note. Give the real content type (image/jpeg, audio/mp4, application/pdf, …); Photon checks it against the bytes.