How your agent hears new messages

Your agent cannot be phoned when a message arrives. So it does the next best thing: it asks DMWire to tell it as soon as someone writes, and waits on the line.

#The idea in one paragraph

Your agent calls wait_for_messages. DMWire holds that call open until a new message arrives on one of your connected accounts, then answers at once with the new messages and a cursor. The cursor is a bookmark: it marks the last message the agent has seen. The agent handles the messages, then calls wait_for_messages again with that cursor, and DMWire waits for the next one. If nothing arrives for a while, the call comes back empty with the same bookmark, and the agent simply asks again.

#What your agent does, step by step

1. Call wait_for_messages (no cursor the very first time: it starts from now).
2. Get back messages (maybe empty) and a cursor.
3. For each message: decide what to do, reply with send_message if needed.
4. Call wait_for_messages again, passing the cursor from step 2. Repeat.

You do not have to write any of this. Telling your agent "keep listening to my WhatsApp and answer questions about X" is enough; the tool description explains the loop to it.

#A real call

With no new messages, after the 5 second timeout:

curl "https://api.dmwire.ai/v1/messages/wait?timeout_s=5" \
  -H "X-API-Key: $DMWIRE_API_KEY"

{
  "messages": [],
  "cursor": "2026-10-17T03:52:22.191Z|"
}

The same through MCP:

curl \
  -X POST https://mcp.dmwire.ai/mcp \
  -H "X-API-Key: $DMWIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "wait_for_messages", "arguments": {"timeout_s": 5}}}'

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "HTTP 200\n{\"messages\":[],\"cursor\":\"2026-10-17T03:52:31.742Z|\"}"
      }
    ],
    "isError": false
  },
  "jsonrpc": "2.0",
  "id": 4
}

When messages arrive, each one comes with its id, the account it arrived on, the channel, the contact (id, phone, name) and the text or media.

#Settings

Up to 50 messages come back per call. At most 2 waits can be open at the same time per account; a third is refused with wait_concurrency (HTTP 429).

#When your agent is not running

wait_for_messages only works while your agent is running. Messages that arrive while it is closed are not lost: they are stored, and an agent that kept its last cursor gets them on its next call. An agent that starts fresh, without a cursor, starts from now.

If you need something to react even when no agent is open (a ping to your own server, an automation tool), use webhooks instead. They push every message to an address you choose.

#wait_for_messages or webhooks?

Last checked against the live service on 2026-10-17.