Quickstart
Create your first persona, give it a rule, and talk to it over HTTP, Telegram or WhatsApp.
This page takes you from a new account to a persona that answers you.
You can do each step below in the app as well. This page also shows the API calls, for scripts and your own clients.
1. Create your first project
Open the app and sign up. Everything in Persona belongs to an organization, so the app asks you to create or choose one when you have none. With no project yet, the app sends you to New project. Give the project a name and create it.
A new project comes with its first persona, named after the project. There is nothing to provision: the persona exists as soon as the request returns.
2. Make an API key
In the app, open Settings, then API keys, and select New API key. The key starts with persona_sk_. It shows only once. Keep it for the next steps.
export PERSONA_KEY=persona_sk_...
export APP=https://app.usepersona.dev3. Find your persona
curl -H "Authorization: Bearer $PERSONA_KEY" $APP/api/projects
export PROJECT=... # the project's id from the answer
curl -H "Authorization: Bearer $PERSONA_KEY" $APP/api/projects/$PROJECT/personasTake the persona's id from the second answer.
export PERSONA=...4. Give it a rule
curl -X POST -H "Authorization: Bearer $PERSONA_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Tone", "content": "Answer in two short sentences, warm and direct." }' \
$APP/api/personas/$PERSONA/instructionsThe persona follows enabled instructions from its next turn on. In the app, the persona's Instructions tab does the same.
5. Talk to it
In the app, open the persona: its Chat tab is a chat with it. Over HTTP, the agent takes a short-lived agent token, not your API key. Ask the API for one, then start a session on the agent's own routes:
TOKEN=$(curl -s -X POST -H "Authorization: Bearer $PERSONA_KEY" $APP/api/personas/$PERSONA/agent-token | jq -r .token)
SESSION=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "message": "Hi! Who are you?" }' \
$APP/eve/v1/session | jq -r .sessionId)
curl -N -H "Authorization: Bearer $TOKEN" $APP/eve/v1/session/$SESSION/streamThe stream sends one JSON event per line. The persona speaks only through its chat tools, so its words are tool calls in the stream: a chat_say call carries the text in its input, chat_file a file id, chat_react an emoji. Plain model text shows on this raw stream only: the Chat tab and the chat channels drop it. Send a follow-up with POST /eve/v1/session/$SESSION and { "message": "..." }. The token lasts 15 minutes. Ask for a new one when it runs out.
6. Reach it on Telegram or WhatsApp
A person links their chat to a persona with a link code:
curl -X POST -H "Authorization: Bearer $PERSONA_KEY" $APP/api/personas/$PERSONA/link-codes
# { "code": "1a2b3c4d", "expiresAt": "...", ... }The persona's Channels tab in the app makes a code too: select a number or a bot.
- Telegram: send
/link 1a2b3c4dto the bot, or openhttps://t.me/<bot>?start=1a2b3c4d. - WhatsApp: send
link 1a2b3c4dto the number.
7. Let it set itself up
Most of a persona's setup is also a tool the persona can use. In a chat, say what you want:
- "From now on, answer in Spanish." The persona saves an instruction.
- "Add the DeepWiki MCP server, https://mcp.deepwiki.com/mcp." The persona saves an MCP server, and its tools are there from the next turn.
- "Every Monday at 9, send me a plan for the week." The persona creates an automation. From a Telegram or WhatsApp chat, the automation reports to that chat.