DOCS v1.0

Herald Agent Documentation

Everything you need to deploy, customize, and manage your AI agents on Telegram. Powered by Nousresearch.

What is Herald Agent?

Herald Agent is a one-click AI agent deployer. It lets you create intelligent Telegram bots powered by Nousresearch — in under 60 seconds, with zero configuration and zero cost.

You bring a Telegram bot token from BotFather. Herald Agent handles the AI, the infrastructure, and the 24/7 uptime.

No API key needed. Herald Agent provides the AI backend. You only need a Telegram bot token.

How it works under the hood

When you deploy an agent:

Your Telegram bot token is validated via getMe
A Telegram webhook is registered pointing to the Herald backend
Every message your bot receives is forwarded to Nousresearch
The AI response is sent back to the user automatically

Quickstart

Deploy your first agent in 3 steps.

[01]

Get a Telegram Bot Token

Open Telegram and message @BotFather.
Send /newbot and follow the prompts.
Copy the token — it looks like 7123456789:AAHxxxx...

[02]

Fill in the Deploy Form

Go to herald-agent.com/#create.
Select a template, give your agent a name, optionally add a personality, and paste your token.

[03]

Hit Deploy & Chat

Click DEPLOY AGENT →. Within 60 seconds your bot is live.
Find your bot on Telegram, send /start, and start chatting.

Getting Your Bot Token

Every Telegram bot has a unique token issued by BotFather. Here's exactly how to get one:

1. # Open Telegram, search for @BotFather
2. Send: /newbot
3. Enter a display name: My Herald Agent
4. Enter a username (must end in "bot"): myheraldagent_bot
5. BotFather replies with your token:
   7123456789:AAHxxxxxxxxxxxxxxxxxxxxx
6. Copy that token → paste into Herald Agent form

Keep your token private. Anyone with your token can control your bot. Never share it publicly.

Templates

Templates define your agent's core behavior and skills. You can always override behavior with a custom personality prompt.

[01] RESEARCHER

Searches, summarizes, and analyzes. Best for staying on top of topics, documents, and news.

[02] TRADER

Market-focused agent. Discusses prices, strategies, and crypto alpha. Built for degens and portfolio managers.

[03] CODER

Writes and reviews code, debugs issues, explains concepts. Supports all major languages.

[04] COMMUNITY

Answers FAQs, moderates conversations, posts announcements. Perfect for DAOs and project groups.

[05] WRITER

Writes threads, blogs, newsletters. Adapts to your tone and style.

[06] CUSTOM

Full control. Define your own skills, behavior, and personality from scratch.

Personality Prompts

The optional personality field lets you override or extend the default template behavior. This is a system prompt that gets injected into every conversation.

Examples

Researcher Personality

You are a sharp crypto researcher. Focus on DeFi and Layer 2 news.
Always cite your sources. Keep answers under 3 sentences unless asked
to elaborate. Speak like a Bloomberg terminal, not a chatbot.

Community Manager Personality

You are the official support bot for $MYTOKEN.
Answer questions about tokenomics, staking, and the roadmap.
Be friendly but concise. Never speculate about price.

Custom Agent Personality

You are a Solana trading assistant named Phantom.
You only discuss Solana ecosystem projects.
Always remind users to DYOR before trading.
Use casual language, like a knowledgeable friend.

Tip: The more specific your personality prompt, the better your agent behaves. Vague prompts produce generic responses.

POST /api/agents/create

Deploys a new agent. Validates the Telegram token, deletes any existing webhook, and registers a new one pointing to the Herald backend.

Troubleshooting

Bot not responding after deploy

This usually means the webhook was not set correctly. Redeploy the agent using the form — this will delete the old webhook and register a fresh one.

Important: If you deployed before May 28, 2026, redeploy. Early versions had a webhook URL bug that is now fixed.

Invalid Telegram bot token error

Check these things:

Copy the full token including the colon: 7123456789:AAHxx...
Do not add spaces before or after the token
Make sure you're using a bot token, not a user account token
Tokens from BotFather are always in format NUMBER:LETTERS

Bot responds with error message

If your bot replies with Sorry, I ran into an error, it usually means the Nousresearch API timed out. This is temporary — try messaging again.

Redeploy an existing bot

Simply go through the deploy form again with the same token. Herald Agent automatically clears the old webhook before setting a new one. No duplicate agents are created.

Check Webhook Status (curl)

# Check what webhook Telegram has registered for your bot
curl "https://api.mogra.site/herald-agent/webhook-info?token=YOUR_TOKEN"

FAQ

Is Herald Agent really free?

Yes. No subscriptions, no token purchases, no hidden fees. Herald Agent is free forever.

Do I need my own AI API key?

No. Herald Agent provides the Nousresearch API access. You only need a Telegram bot token from BotFather.

Can I deploy multiple agents?

Yes. Each Telegram bot token creates a separate agent. Deploy as many as you need.

What AI model powers the agents?

Agents are powered by hermes-3-llama-3.1-405b from Nousresearch — a fast, capable language model optimized for real-world assistant tasks.

Does my agent remember previous conversations?

Currently each message is processed independently. Conversation memory is on the roadmap.

Can I update my agent's personality after deploying?

Yes. Simply redeploy with the same token and a new personality prompt. The old webhook is replaced automatically.

Is my Telegram token stored?

Your token is encoded into the webhook URL and never stored in a database. Only Telegram holds the webhook URL, and it is never logged or persisted on our servers.

Discord support?

Coming soon. Discord is the next platform on the roadmap.