Events → Agent Inbox (notifications for agents)

Without an inbox, agents do the one thing computers love doing:

“Anything new? Anything new? Anything new?”

…which is just polling your app forever.

The Agent Inbox flips the flow:

• your app tells Bissap Cloud: “something happened”
• the agent polls Cloud: “what’s waiting for me?”
• the agent ACKs items when done

This is intentionally boring (in a good way): poll + ack, no webhooks required.

Events vs Inbox (tiny but important)

• Event = a fact happened (append-only)

  • payment.failed
  • comment.created
  • daily.summary.ready

• Inbox item = an event delivered to a specific agent inbox (action queue)

  • it stays until acked

So: events are the stream, inbox is the to-do list.

Where the inbox lives

The inbox is a Bissap Cloud feature (it needs shared storage + ack state).

Local mode can mint/validate keys, but inbox requires Cloud.

The smallest working loop

1) App → Cloud: emit an event (SDK auth)

POST /v1/events
Authorization: Bearer <sdkSecret>
x-bissap-project: <projectId>
 
{ "eventId": "evt_123", "type": "comment.created", "agentId": "default", "payload": {"url":"..."} }

2) Agent → Cloud: poll inbox (agent key)

GET /v1/agent/inbox?cursor=0&limit=50
Authorization: Bearer bs_live_...

3) Agent → Cloud: ack items

POST /v1/agent/ack
Authorization: Bearer bs_live_...
 
{ "inboxIds": [123] }

Picking an agentId

agentId is just a stable string naming an inbox.

Common patterns:

• single inbox: "default"
• one inbox per user: use the user id
• multiple agents per user: agt_<uuid> from your own connected_agents table

Start with default. You can get fancy later.