Choose a Photon project, create a server-side API key, and prepare your development environment.
Use one project for your first agent. Its channel connections, messages, Voice
profiles, and API key belong together; a key from another project cannot access
them.
1
Choose your project
Open the Photon Beta dashboard. Create an organization
and project if you do not have one, or select your project in the switcher
at the top of the sidebar.Open Settings and copy the Project ID, beginning with pho_prj_.
Keep this project selected for the rest of the walkthrough. Ask an
organization admin for access if you cannot manage its keys or channels.
2
Create an API key
Open API keys in the project sidebar, then New API key. Name it
First agent, choose an expiry, and select the permissions it needs:
Permission
When you need it
project:read
Read messages for the iMessage and email tests.
project:write
Send the agent’s replies.
platforms:read
Read channel configuration or a Voice profile with a client.
platforms:write
Run the optional client examples that assign a shared line or connect a domain. Not needed when you configure them in the dashboard.
The messaging program needs project:read and project:write. Add platform permissions only for the setup examples you run. Sample dashboard preview; no key is shown.
Select Create key. Copy and save the key when it appears on the page:
it is shown only once. If you lose it, create a replacement and revoke
the old key rather than trying to retrieve its plaintext.
3
Set your environment variables
In the terminal where you will run the examples, set your project ID and
key. Replace the placeholders locally; do not paste real credentials into
shared code or screenshots. Choose the block for your shell; macOS uses
zsh by default. Both prompts keep the key out of shell history.
export PHOTON_PROJECT_ID="pho_prj_REPLACE_WITH_YOUR_PROJECT_ID"read -rs "PHOTON_API_KEY?Photon API key: "; echoexport PHOTON_API_KEY
export PHOTON_PROJECT_ID="pho_prj_REPLACE_WITH_YOUR_PROJECT_ID"read -rsp "Photon API key: " PHOTON_API_KEY; echoexport PHOTON_API_KEY
Your application’s secret manager is a better place for a deployed key.
Run these examples on your computer or server, never in a browser or mobile
app. Do not commit the key or a local environment file. All HTTP examples
use https://api.photon.codes with Authorization: Bearer <key>.
4
Install the client for your language
Create a working directory for the examples. Choose one language; you do
not need all four. These setup examples use published client 0.5.0.
mkdir photon-first-agent && cd photon-first-agentnpm init -ynpm pkg set type=modulenpm install @photon-ai/[email protected]
cargo new photon-first-agentcd photon-first-agentcargo add photonhq-api@=0.5.0cargo add tokio --features macros,rt-multi-thread
mkdir photon-first-agent && cd photon-first-agentgo mod init example.com/photon-first-agentgo get github.com/photon-hq/api/packages/[email protected]
Use Node.js 24 or later for the TypeScript walkthrough, Python 3.11 or
later, Rust 1.88 or later, or Go 1.25 or later. The messaging programs
explain their additional HTTP dependencies where needed.
