The Needs you inbox (allternit-api, Clerk session or API key). The list is derived live from where the work already lives: held email (agent_email_outbound), approvals (gateway_approvals), threads in needs_you/review, missed calls and unanswered messages (bot_events), failed sends (channel_message_log) and vendor tickets (vendor_tickets). Only the caller’s own bots appear. Migration V232__inbox_needs_you.sql adds inbox_state, which remembers dismissals and snoozes; nothing else is stored. GET /api/v1/inbox also still returns the older notification items (items, unreadCount) unchanged.

​
List

GET /api/v1/inbox?scope=needs_you&minutes=30 scope=needs_you returns only the aggregate. Without it the older fields come back too. minutes (1 to 1440, default 30) is how long an inbound message may wait before it counts as unanswered.
Newest first. kind is email_draft, approval, held_send, thread, missed_call, unanswered, failed_send, vendor_result or draft (a message a bot’s autonomy level kept as a draft instead of sending; source is its channel, person who it was for). id is stable and prefixed by its source (email:, approval:, thread:, call:, reply: per thread, failed:, ticket:, draft:). primary.action is approve (run the approval; the client calls approve), or open, reply, callback (the client opens the bot’s phone). actions lists which of the three POST routes apply: approve is absent for kinds that can only be opened.

​
Act

All three are POST /api/v1/inbox/:id/<action>; :id is URL-encoded (approval%3Aap1). A missing, already handled or foreign item answers 404 {"error", "code":"NOT_FOUND"}.
  • approve with an optional {"decision":"deny"} (default approve; anything else is 400 BAD_DECISION).
    • email_draft: approves or rejects the held mail (decide_outbound_for_thread). 200 {"id","result":{"state":"sent"|"rejected"}}; 502 EMAIL_DECISION_FAILED when mailflare can’t action it.
    • approval: answers the gateway approval as the signed-in person (respond_approval). 200 {"id","result":{"approvalId","state":"approved"|"denied"}}.
    • held_send: same, and on approve the held text is posted through the channel gateway under the same correlation id: result.send.state is sent, unconfirmed, rejected, channel_offline, no_binding, not_sent or error.
    • any other kind: 400 {"code":"NOT_APPROVABLE"}.
  • dismiss: 200 {"id","state":"dismissed"}.
  • snooze with optional {"minutes":60} (1 to 20160): 200 {"id","state":"snoozed","until":"<RFC 3339>"}.
A dismissed or snoozed item reappears when its at moves past the time it was handled (a newer message, a thread asking again), or when a snooze runs out. Every action writes an inbox.changed event ({"itemId","action"}) on the item’s bot. The notification feed sends it as kind: "inbox_changed" so other devices refresh; clients never raise a notification for it.

​
Turning it on

Nothing to configure and no new environment variables. Held email needs the same mailflare setup the bot’s email address uses (see Starting conversations); with it unset, approving an email answers 502 EMAIL_DECISION_FAILED and the item stays. A channel whose credentials aren’t set answers channel_offline in result.send, and the approval itself is still recorded.