Des agents dans vos discussions

Votre premier agent

1. Ouvrez @agentfather et envoyez /newagent. Choisissez un nom et un pseudo unique terminé par _agent (7–32 caractères).
2. Cliquez sur le bouton du jeton dans la réponse. Confirmez et conservez-le sur votre serveur. Il s’affiche une seule fois dans une fenêtre séparée, jamais dans l’historique.
3. Lancez l’exemple Python sur votre serveur puis écrivez à l’agent. Sa logique et son IA tournent chez vous : créer l’agent ne déploie pas de modèle.

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

ZNOSIN_AGENT_TOKEN · Python 3.10+

Disponible en v1

Recevez les actions avec GET /updates?callbacks=true. Une mise à jour contient message ou callback. Les données viennent du serveur et l’utilisateur est callback.from. Vérifiez les droits dans votre système. Répondez via POST /callbacks/{id}/answer avec text et showAlert. Le client attend jusqu’à 10 secondes ; l’action expire après 120 secondes. Une réponse identique peut être répétée. Les actions ne créent pas de message. Les webhooks et l’envoi de fichiers ne sont pas encore disponibles.

Référence API

HTTPS et JSON. Envoyez Authorization: Bearer <token>. Le succès contient ok et result ; les erreurs ok:false et error. Les dates sont en millisecondes Unix. Le schéma OpenAPI détaille tous les champs.

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": "fr",
  "commands": [
    {
      "command": "help",
      "description": "Guide Agent API"
    }
  ]
}

Commandes et boutons

Ajoutez markup à POST /messages ou PATCH /messages/{id} : les lignes inline contiennent des actions (text, id, data), des liens HTTPS (text, url) ou des mini-applications (text, appId). Le clavier reply envoie des réponses ordinaires à l’agent. oneTime le masque après utilisation ; type remove le retire. Lors d’une modification, omettez markup pour conserver les boutons ou envoyez null pour les supprimer.

{
  "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"
        }
      ]
    ]
  }
}

Saisissez / dans le chat pour voir les commandes. Dans un groupe, une commande choisie cible un seul agent avec /command@nickname. Les menus acceptent les sept langues. Enregistrez jusqu’à 20 commandes par langue avec PUT /commands.

/setcommands @nickname fr · @agentfather

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

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

Langue de l’utilisateur

Les messages entrants et les actions sur les boutons contiennent from.language_code : en, ru, uk, de, fr, pl ou zh. Il s’agit de la langue d’interface de l’expéditeur au moment de l’événement, y compris dans les groupes. Les anciens événements, les préférences inconnues et les messages des agents renvoient null ; choisissez une langue de secours dans votre code. Les redémarrages et les nouvelles tentatives conservent la valeur. Les messages suivants, les modifications et les réglages d’un autre appareil ne la changent pas. Un transfert porte la langue de la personne qui transfère, pas de l’auteur initial. C’est une préférence du client, pas une détection de langue ni une autorisation. Les clients envoient X-Znosin-Language ; les langues prises en charge dans Accept-Language servent de repli. Votre code traduit les réponses et les boutons. AgentFather suit déjà l’interface ; /language ru fixe une langue et /language auto rétablit le choix automatique.

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

Accès et confidentialité

L’agent ne peut pas commencer une conversation privée. Une personne écrit d’abord ; /stop bloque les messages et /start reprend avec de nouvelles entrées. Dans les groupes, il voit seulement les commandes comme /help ou /help@name_agent et les réponses à ses messages après son arrivée. Aucun historique cité, ancien message, mail, portefeuille ou clé du propriétaire. Le retirer du groupe révoque son accès.

Livraison fiable

Le long polling attend jusqu’à 25 secondes et répond à l’arrivée d’un message. Utilisez un consommateur par agent et sauvegardez nextOffset, même sans résultat. Réessayez avec les mêmes clientId et contenu. La file conserve au plus 10 000 entrées pendant 24 heures ; reset signale une expiration ou saturation. Limites : 180 requêtes/minute, 60 envois/minute par agent, 30 par discussion. Respectez Retry-After pour 429 et 503, et espacez les tentatives après une erreur réseau.

Gérer votre agent

Commandes de @agentfather : /myagents, /token @pseudo, /disable @pseudo, /enable @pseudo, /setname @pseudo Nom et /setdescription @pseudo Description. La rotation révoque immédiatement l’ancien jeton. La désactivation révoque le jeton et vide la file. Après réactivation, émettez-en un nouveau. /language en|ru|uk|de|fr|pl|zh choisit la langue ; /language auto suit l’interface. Maximum 20 agents par propriétaire.

Connectez un modèle IA

Remplacez l’écho par un appel de modèle sur votre serveur. Informez les utilisateurs des données transmises au fournisseur. Traitez messages et fichiers comme non fiables, limitez les droits des outils et demandez confirmation humaine pour les actions sensibles. Ne placez jamais les jetons Znosin ou clés du modèle dans les prompts ou le code client.