Skip to Content
persona

Channels

How people reach a persona on WhatsApp, Telegram and the web, how a chat links to a persona, and what goes in and out.

People talk to a persona where they already are. Persona has three channels:

ChannelRuns onA person starts by
WhatsAppthe WhatsApp Business platform, straight on Metasending link <code> to the number
Telegramthe Telegram Bot APIsending /link <code> to the bot, or opening its ?start=<code> link
Webthe agent's HTTP APIthe app's Chat tab, or a client with an agent token

Slack and iMessage are coming soon.

Numbers and bots

Persona has one shared WhatsApp number, on Meta, and one shared Telegram bot. They serve every project. Persona's older number on Kapso is legacy: the chats already on it keep working, but the app no longer shows it or adds new ones.

A project can add its own numbers and bots. An own number or bot serves only that project's personas. In the app, they are in the project's settings, under WhatsApp and Telegram.

  • WhatsApp. In the project's settings, open WhatsApp, then Add and Bring your number. Give the number's phone number ID and messaging account ID (both on your Meta app's WhatsApp > API Setup page), the app's ID and secret, and a system user's token for the app. Persona tests them with Meta, points the app's webhook at Persona, subscribes the number's account, registers the number if it is not registered yet, and keeps the keys on the line, which never sends them back. A refused step shows Meta's own words. Removing the number leaves it in your Meta account.
  • Telegram. Make a bot with BotFather, then send its token to POST /api/projects/{projectId}/telegram-bots. Persona checks the token, sets the bot's webhook and keeps the token as a secret.

Removing a bot or a number also removes every chat link on it. A removed number stays in your Meta account.

A link ties one chat to one persona. A chat is one person on one number or bot.

  1. The creator makes a link code for a persona: on the persona's Channels tab in the app, or with POST /api/personas/{personaId}/link-codes. A code is eight characters. It works once, for 24 hours.
  2. The person sends the code from their phone:
    • on WhatsApp: link 1a2b3c4d;
    • on Telegram: /link 1a2b3c4d, or the bot's link https://t.me/<bot>?start=1a2b3c4d.
  3. Persona answers You're connected to <persona>. Say hi!, and every later message goes to that persona.

A code works on the shared numbers and bot, and on the own numbers and bots of the persona's project. A new code moves the chat to another persona. On Telegram, /start with no code says which persona the chat is linked to.

A message from a chat with no link gets a short reply that explains how to link.

What comes in

A person sendsThe persona gets
Textthe text
A photo or a PDFthe saved file's id, and the file itself, so the model sees it
A voice noteits words, with the saved file's id. Kapso's number uses Kapso's transcript. On Meta numbers and Telegram, Persona transcribes it with microsoft/mai-transcribe-2.
Another filethe saved file's id, with its name and type
A reply that quotes a messagethe text, and the quoted message's words. On Meta numbers.

Every photo, voice note and file is saved to the persona's files first. A message with no text and no file gets the reply "I can't read that kind of message yet."

What goes out

A persona writes plain text, like a person texting. Bold works. Headings become bold lines, and tables become plain-text blocks.

The persona talks only through its chat tools: one sends a message, one sends a file, and one reacts. Each message goes out the moment the persona sends it, so it can talk in steps. A file goes out as a real attachment: a photo, a voice note, a video or a document. Links stay in the sentence on both channels. Telegram and the legacy WhatsApp numbers show a preview of the first one; Meta numbers show none. WhatsApp shows a named link as the name with the address in brackets, and an email or phone address stays as written. The persona can also react to any of the person's messages from the last week with an emoji, or reply to one so it shows as a quote.

If a turn fails, the person gets "Something went wrong on my side. Try again in a moment."

There are no buttons. When the persona needs a yes before an action, it asks in words.

Chats and sessions

Each linked chat is one long session with its persona. A session ends after seven idle days, and the next message starts a new one with no history. Telegram has one session per bot, chat and persona. WhatsApp has one per number, person and persona.

Two commands work in every linked chat. /clear forgets the conversation so far and keeps the session. /reset starts a new session. The persona answers Cleared our chat. or Started a new chat. When a turn fails, the persona says so and names both commands.

An automation that the persona creates in a chat reports back to that chat. See Automations.

The web

The web channel is the agent's own HTTP API at /eve/v1/*, on the app's origin. It takes an agent token: a 15-minute token for one persona, from POST /api/personas/{personaId}/agent-token. Each conversation is a new session. Quickstart shows the calls.

The app's Chat tab is a client of it. Each new chat is a session; New chat in the composer starts another one.

Status. Group chats on Telegram and WhatsApp are not supported yet: a persona answers direct messages only.

On this page