Agents in your conversations

Your first agent

1. Open @agentfather and send /newagent. Choose a name and a unique nickname ending in _agent (7–32 characters).
2. Press the token button in the manager’s reply. Confirm issuance and save the token on your server. It appears once in a separate dialog, never in chat history.
3. Run the Python example on your server, then write to your agent. Its logic and AI run in your infrastructure; creating an identity does not host a model.

curl https://znosin.com/api/agent/v1/me \
  -H "Authorization: Bearer $ZNOSIN_AGENT_TOKEN"

ZNOSIN_AGENT_TOKEN · Python 3.10+

Available in v1

Read callbacks with GET /updates?callbacks=true. Each update contains message or callback. Callback data is supplied by the server; the actor is callback.from. Check your own business permissions before changing data. Answer using POST /callbacks/{id}/answer with text and showAlert. The client waits up to 10 seconds; callbacks expire after 120 seconds. Answering twice with the same payload is safe. A callback does not create a chat message. Webhooks and outgoing media uploads are not available yet.

API reference

HTTPS and JSON. Send Authorization: Bearer <token>. Success contains ok and result; errors contain ok:false and error. Message times are Unix milliseconds. Download the OpenAPI schema for complete request and response fields.

https://znosin.com/api/agent/v1

POST /api/agent/v1/messages

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Hello!",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee"
}

PUT /api/agent/v1/commands

{
  "language": "en",
  "commands": [
    {
      "command": "help",
      "description": "Agent API guide"
    }
  ]
}

Commands and buttons

Add markup to POST /messages or PATCH /messages/{id}: inline rows contain callback buttons (text, id, data), HTTPS links (text, url), or mini-app buttons (text, appId). Reply keyboards send ordinary messages in reply to the agent. oneTime hides the keyboard after use; type remove removes it. Omit markup when editing to preserve it, or pass null to clear the message buttons.

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Choose an action",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee",
  "markup": {
    "type": "inline",
    "rows": [
      [
        {
          "text": "Confirm",
          "id": "confirm",
          "data": "confirm:123"
        },
        {
          "text": "Cancel",
          "id": "cancel",
          "data": "cancel:123"
        }
      ],
      [
        {
          "text": "Website",
          "url": "https://znosin.com"
        },
        {
          "text": "Calculator",
          "appId": "calculator"
        }
      ]
    ]
  }
}

Type / in a chat to see available commands. In groups, choosing a command targets one agent with /command@nickname. Command menus support all seven interface languages; developers register up to 20 commands per language with PUT /commands.

/setcommands @nickname en · @agentfather

{
  "type": "reply",
  "rows": [
    [
      "Yes",
      "No"
    ],
    [
      "Help"
    ]
  ],
  "oneTime": true
}

8 rows × 4 buttons · 64 characters/label · 256 UTF-8 bytes/data · HTTPS

User language

Incoming messages and button callbacks include from.language_code: en, ru, uk, de, fr, pl or zh. It records the sender’s interface language when the event is created, including in groups. Older events, unknown preferences and agent-generated messages return null; choose your own fallback. The value survives restarts and retries and does not change with later messages, edits or device settings. Forwarded messages carry the forwarding person’s language, not the original author’s. This is a client-provided preference, not text-language detection or an authorization signal. Clients send X-Znosin-Language; supported Accept-Language preferences are the fallback. Your code selects translated replies and buttons. AgentFather already follows the interface language; /language ru pins a language and /language auto restores automatic selection.

{
  "from": {
    "id": "USER_ID",
    "name": "Alex",
    "nickname": "alex",
    "language_code": "en"
  }
}

Access and privacy

An agent cannot start a private conversation. A person writes first; /stop blocks further messages and /start resumes with new inputs. In groups it sees only commands such as /help or /help@name_agent and replies to its own messages, after it joins. It receives no quoted history, old messages, owner mail, wallet or account keys. Removing it from a group revokes access.

Reliable delivery

Long polling waits up to 25 seconds and wakes on new messages. Use one consumer per agent and save nextOffset, including empty results. Retry sending with the same clientId and payload. The queue holds at most 10,000 inputs for up to 24 hours; reset signals expiration or overflow. Limits: 180 requests/minute, 60 sends/minute per agent, 30 sends/minute per chat. Respect Retry-After on 429 and 503; use backoff for network failures.

Manage your agent

Use /myagents, /token @nickname, /disable @nickname, /enable @nickname, /setname @nickname Name and /setdescription @nickname Description in @agentfather. Rotation revokes the previous token immediately. Disabling revokes the token and clears pending inputs. After enabling, issue a new token. /language en|ru|uk|de|fr|pl|zh selects a language; /language auto follows your interface. Up to 20 agents per owner.

Connect an AI model

Replace the echo in the example with a model call on your server. Tell users what you send to the model provider. Treat messages and files as untrusted input, isolate tool permissions, and require human confirmation for sensitive actions. Never put Znosin tokens or model keys in prompts or client code.