companion post to OpenRouter Provider for WordPress
Dot Agents Press is a WordPress plugin for managing and deploying conversational AI agents. It provides a WP Admin interface for creating agents with individual configurations, embeds them via shortcode or REST API, and connects them to Telegram through a native webhook handler.
Combined with the OpenRouter Connector, it forms a complete self-hosted agent stack on WordPress 7.0.
Architecture overview
Each agent in Dot Agents Press is a WordPress custom post with configuration fields: system prompt, welcome message, model, temperature, and an optional per-agent API key override. The plugin exposes two surfaces:
- Shortcode — embeds a chat widget in any page or post
- REST API —
POST /wp-json/dot-agents-press/v1/chatfor headless use
The Telegram integration adds a third endpoint (/wp-json/dot-agents-press/v1/telegram/webhook) that routes inbound messages to the configured agent and replies via Telegram’s sendMessage.
The system prompt assembly follows a layered priority:
1. .agents/system-prompt.md (filesystem, repo root)
2. .agents/agents.md (filesystem, repo root)
3. Agent's DB system_prompt (WordPress options / CPT field)This means agent instructions can live in version control — committed, diffed, reviewed — without depending on the database.
Requirements
| Requirement | Version |
|---|---|
| WordPress | ≥ 6.0 (7.0 for Connectors API) |
| PHP | ≥ 8.0 |
| PHP extension | openssl (for key encryption) |
Installation
cd wp-content/plugins/
git clone https://github.com/aiiddqd/dot-agents-press.gitActivate from Plugins → Installed Plugins, then go to AI Agents → Settings and configure a global API key — or use wp-config.php constants:
define( 'DAP_OPENAI_API_KEY', 'sk-…' ); // OpenAI or OpenRouter key
define( 'DAP_ANTHROPIC_API_KEY', 'sk-ant-…' ); // Anthropic keyConstants take precedence over the Settings UI.
If the OpenRouter Connector is installed and configured, Dot Agents Press will use it automatically through WP AI Client — no separate key needed.
Creating an agent
Navigate to AI Agents → Add New. Relevant fields:
Name: Support Bot
System Prompt: You are a helpful assistant for [project context].
Answer questions about products, policies, and orders.
Welcome Message: Hi! How can I help you today?
Model: anthropic/claude-sonnet-4-5 (any OpenRouter model string)
Temperature: 0.7
Provider: openai | anthropic | custom
API Key Override: (leave blank to use global key)The custom provider type accepts any OpenAI-compatible endpoint — useful for local models (Ollama, LM Studio) or other proxies.
Shortcode embed
// By agent ID
[dot_agent id="3"]
// By agent slug
[dot_agent slug="support-bot"]The widget is accessible by default: keyboard-navigable, aria-live region for screen readers, auto-resizing textarea. CSS custom properties expose theming without overriding core styles:
.dap-chat-widget {
--dap-user-bg: #7c3aed;
--dap-header-bg: #5b21b6;
--dap-radius: 8px;
--dap-font-size: 0.95rem;
}REST API
Endpoint: POST /wp-json/dot-agents-press/v1/chat
Request:
{
"agent_id": 3,
"messages": [
{ "role": "user", "content": "What is your return policy?" }
]
}Response:
{
"role": "assistant",
"content": "Returns are accepted within 30 days of purchase...",
"model": "anthropic/claude-sonnet-4-5",
"usage": {
"prompt_tokens": 58,
"completion_tokens": 94,
"total_tokens": 152
}
}The endpoint requires edit_posts capability by default. Pass the full messages array for multi-turn conversations — the plugin has no server-side session state; history management is the client’s responsibility.
Telegram integration
1. Create a bot
Open @BotFather on Telegram and run /newbot. Copy the token it returns.
2. Get your Telegram user ID
Message @userinfobot. Copy the numeric Id. Dot Agents Press uses this to lock the bot to a single authorized user (personal assistant mode). For multi-user bots, leave the field empty and implement your own authorization logic via the filter hooks.
3. Configure the plugin
Go to Settings → Dot Agents Config:
| Field | Value |
|---|---|
| Telegram Bot Token | Token from @BotFather |
| Telegram User ID | Numeric ID from @userinfobot |
| Webhook Secret | Any random string (optional) |
| Default Agent ID | Post ID of the agent to use |
4. Register the webhook
wp dap telegram set-webhook
wp dap telegram statusExpected output:
URL: https://yoursite.com/wp-json/dot-agents-press/v1/telegram/webhook
Has custom cert: no
Pending updates: 0The site must be publicly reachable over HTTPS — Telegram requires a valid certificate. For local development, use ngrok to expose the DDEV environment:
ddev share
# copy the https URL, then:
wp dap telegram set-webhook --url=https://your-ngrok-url.ngrok-free.app/wp-json/dot-agents-press/v1/telegram/webhook5. Webhook flow
Telegram → POST /wp-json/dot-agents-press/v1/telegram/webhook
│
TelegramBridge
│
1. Verify webhook secret (if set)
2. Authorize user (telegram_authorized_user_id)
3. Resolve agent (default_agent_id)
4. Build system prompt:
.agents/system-prompt.md → priority 1
.agents/agents.md → priority 2
DB system_prompt → priority 3
5. AI API call via DAP_API::handle_chat()
6. sendMessage(chat_id, reply)
│
Telegram ←─────┘Managing the webhook
wp dap telegram set-webhook # Register or update
wp dap telegram delete-webhook # Remove
wp dap telegram status # Show current config and pending updatesThe .agents Protocol
Dot Agents Press follows the .agents Protocol — a vendor-neutral convention for storing agent configuration in the filesystem.
The plugin reads from the project root (one directory above ABSPATH):
project/
├── .agents/
│ ├── system-prompt.md ← primary instructions (priority 1)
│ └── agents.md ← project context (priority 2)
└── public/
└── wp-config.php ← WordPress root (ABSPATH)If .agents/agents.md is absent, the plugin checks AGENTS.md at the project root as a legacy fallback.
This makes agent configuration portable: the same .agents/ directory works with Cursor, Claude Code, and other tools that have adopted the convention — no migration needed when switching between editors or agent runtimes.
Multi-agent patterns
Nothing prevents running several agents on the same install:
// Route by keyword in a custom webhook handler
function my_route_agent( string $text ): int {
if ( str_contains( $text, 'order' ) || str_contains( $text, 'refund' ) ) {
return 4; // Support agent
}
if ( str_contains( $text, 'price' ) || str_contains( $text, 'plan' ) ) {
return 5; // Sales agent
}
return 3; // Default agent
}Or use Telegram inline keyboards to let the user select which agent to start a conversation with.
Supported providers
| Provider | provider value | Example model strings |
|---|---|---|
| OpenAI | openai | gpt-4o, gpt-4o-mini, gpt-4-turbo |
| Anthropic | anthropic | claude-opus-4-5, claude-sonnet-4-5 |
| Custom | custom | Any OpenAI-compatible endpoint; free-text model |
When using the OpenRouter Connector, set provider to custom and enter any OpenRouter model string (e.g. meta-llama/llama-3.3-70b-instruct), or set a global OpenAI-compatible endpoint in Settings.
Summary
Dot Agents Press adds a first-class agent management layer to WordPress without rebuilding what core already provides. The Connectors API handles provider abstraction; Dot Agents Press handles agent identity, prompt assembly, and channel routing.
For site owners: a no-code WP Admin UI for creating and managing agents, embeddable anywhere.
For developers: a REST API, per-agent key override, .agents protocol support, and a Telegram webhook stack that takes ~10 minutes to configure.
The combination of Dot Agents Press + OpenRouter Connector produces a self-hosted OpenClaw alternative on infrastructure the developer already controls.
