Skip to main content

How do I talk to my agent through the API?

Send messages to a deployed agent with UserAgent/Message/Send and get the reply by WebSocket, polling or webhook.

You can chat with a deployed agent from your own app or backend with the Agent Messaging API. The agent must already be deployed and Running.

What you need

  • An API key from one of your Wiro projects (see How do I get an API key?). For a team agent, use the key of a project in that team; a personal project's key can't reach a team agent. If your project uses signature authentication, sign the request as for any other call (see your first API request).

  • The agent's guid. It's the last part of the agent page's address (/panel/agents/<guid>), or call POST /UserAgent/MyAgents.

Send a message

curl -X POST "https://api.wiro.ai/v1/UserAgent/Message/Send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "useragentguid": "YOUR_AGENT_GUID",
    "message": "Draft three post ideas for next week",
    "sessionkey": "user-42"
  }'

  • sessionkey keeps a conversation together: the agent remembers the context within one session key. Use one per end user or thread, such as user-42. Without it, everything goes into the default session.

  • Optional: model runs this one message on another of the agent's models, and callbackurl sets a webhook (below). Files can be sent as multipart attachments.

Send answers right away with an agenttoken and a messageguid. The reply comes later.

Get the reply

  1. Agent WebSocket: receive the reply as it's written (see Agent WebSocket).

  2. Polling: call POST /UserAgent/Message/Detail with the agenttoken until the status is agent_end (done), agent_error or agent_cancel.

  3. Webhook: pass a callbackurl, and Wiro POSTs the result to it when the agent finishes.

Webhook tips

  • Wiro tries each webhook up to 3 times, 2 seconds apart, and only an HTTP 200 answer counts as delivered. Answer 200 quickly and do your processing afterwards.

  • Webhooks aren't signed. Check that the messageguid is one you sent, use an HTTPS address, and treat Message/Detail as the source of truth.

  • A message cancelled while it's still queued sends no webhook.

  • Callbacks for model runs (the Run API) work differently: see model run callbacks.

If Send fails

Send refuses the message when the agent isn't Running or has no credits left, and says why, for example "Agent is stopped. Start it from the agent panel before sending messages." See Why won't my agent start or reply? and My agent says it has no remaining credits. To deploy an agent through the API, see Can I pay for an agent from my Wiro balance?

Docs: Message/Send, tracking a message, sessions, webhook retries and webhook security.

Did this answer your question?

Related Articles