Skip to Content
persona

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.dev

3. 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/personas

Take 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/instructions

The 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/stream

The 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 1a2b3c4d to the bot, or open https://t.me/<bot>?start=1a2b3c4d.
  • WhatsApp: send link 1a2b3c4d to 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.

What next

  • Personas: every part of a persona in detail
  • Channels: shared and own numbers and bots, and link codes
  • API: everything above, and the rest

On this page