STACK
MENU
DOCS / API REFERENCE / WAKE-UPS, CALENDAR AND MEETINGS

Wake-ups, Calendar and Meetings API

What starts an agent, its calendar, and the meetings it joins. The steps are in the Wake-ups, Calendar and Meetings guides.

Wake-ups

A wake starts an agent with a task when something happens to it. Every one of your agents has wake-ups, with or without an agent account. An account's agent is woken when mail, a text, a Telegram message to its bot, a voicemail or a call transcript arrives, a call rings on its number, post arrives at its address, a payment comes in or a calendar event reaches its start. Any agent is woken when its schedule fires, when another of your agents deposits a drop-off for it, when a person it works with through a connected service such as RentAHuman applies, delivers or writes (the source service_event, which needs no rule and carries only the service, the kind of event and its ids), and when a pending item it waited on ends (the source decision: an approval, a review, an order, a purchase, a drop-off it left and the rest). Nothing wakes the agent for mail, texts, Telegram messages, voicemail, calls, post or payments until a rule says so; an incoming call needs no rule (ring_incoming_calls switches it off), and an accepted invite, a schedule, a drop-off from your own agent and a decision are your own choice already. The task is your own text, or a plain default that says only what happened ("New email.", "Call ended.", "Intent approval: approved."). Nothing a stranger wrote is ever part of it.

  • GET /v1/agents/:agentId/wakes?status&limit&cursor - the wakes of one agent. status=open is its queue: delivered and not yet acknowledged, oldest first; one nobody acknowledged ends as expired after 30 days. Each has account_id (null for an agent with no account), source (email, sms, voicemail, call, incoming_call, payment, post, invite, schedule, handoff, decision), task, status (pending, delivered, acknowledged, refused, expired), delivered_via (webhook or mission) and event, which holds facts such as the message id, for an incoming call the call id and answer_by, for a handoff the drop-off id and the agent that left it, or for a decision item_kind, item_id and result, never the content. Also returns the rate window: wakes accepted and wakes dropped by the limit.
  • GET /v1/agents/:agentId/wakes/:wakeId - one wake. POST .../acknowledge - the agent picked it up (saying it twice is fine). Open to the agent itself (X-Passport-Token) and to the owner.
  • GET|PUT /v1/trust and GET|PUT /v1/agents/:agentId/trust - the trust switch, for the account and for one agent: { trust: "ask_first" | "trust_agents" } (null for an agent follows the account again). Reads return { agent_id, trust, effective, source }. STACK starts a new account on trust_agents, where card purchases, orders on your own supplier account and governance changes made with your own API key do not wait for a person; limits, revoked agents, policy review rules and the browser-only actions still apply. Owner or admin only; an agent is refused.
  • GET|PUT /v1/wake/settings and GET|PUT /v1/agents/:agentId/wake/settings - the account defaults, and one agent's own: enabled, time_zone, quiet_start and quiet_end with quiet_mode (hold or drop; a decision is only ever held), rate_limit_max (none unless you set one) per rate_limit_window_seconds (default 3600) for every source but an incoming call and a decision, which no rate limits, delivery (the order of mcp, webhook, mission; the queue is always last), invite_lead_minutes, ring_incoming_calls (true by default; false sends incoming calls straight to voicemail) and webhook_url. A field left out stays; null inherits.
  • GET|POST /v1/wake/rules, PUT|DELETE /v1/wake/rules/:ruleId and GET|POST /v1/agents/:agentId/wake/rules - which source wakes which agent: { name, source, filters?: { from, min_amount_cents }, task?, enabled? }. At most 50 per scope; an agent's own rules come before the defaults.
  • GET|POST /v1/agents/:agentId/wake/schedules and PUT|DELETE .../:scheduleId - { name, cron, time_zone?, task?, enabled? }. Five fields or @hourly, @daily, @weekly, @monthly, read in the time zone; no more often than every 5 minutes, at most 20 per agent. A fire missed while STACK was down wakes the agent once.
  • POST /v1/agents/:agentId/wake/webhook/rotate-secret and POST .../wake/webhook/test - a new signing secret (shown once; an OAuth token gets a note instead; the old one verifies for 24 hours) and a signed test that wakes nothing.

Every route that changes settings, rules, schedules or the webhook needs the owner or an admin (agent credentials are refused) and is never metered. Each wake itself is one metered action. When you have a control socket, an account agent's wake is put to your decider as wake.deliver first, and a refused wake is never charged. Quiet hours hold a wake until they end, or drop it; a call that rings is not held or dropped, it goes to voicemail. Past the rate limit a wake is dropped and counted; an incoming call past it goes to voicemail. The same event from the provider is one wake.

How a wake reaches the agent

In the order you choose: a notification on an open MCP session of the agent (a notifications/message from logger stack.wake, which is never the delivery on its own, since a client may not show it to the model); a signed POST to the agent's own https endpoint; and always the queue above, which needs no setup: an agent with no live session and no webhook finds its wakes there on its next session. A push that fails is retried with backoff before the queue takes it, and a wake that was never delivered within 24 hours expires.

The endpoint receives Standard Webhooks (webhook-id is the wake id on every retry, so ignore one you have seen; webhook-timestamp; webhook-signature, an HMAC-SHA256 over id.timestamp.body with the whsec_ secret). The body is { type: "stack.wake", version: "2", wake_id, account_id, agent_id, mission_id, source, task, occurred_at, event, sender_tags? }. Nothing a stranger wrote is in it: read the message itself through the account's messages. The SDKs verify a request with verifyWakeWebhook and verify_wake_webhook.

Calendar

The agent has one calendar. Its own events and the invites sent to its address are the same kind of thing: an event is stored once, with its time zone and its repeat rule (RFC 5545), and its occurrences are worked out when you read the agenda. Making, changing and cancelling an event, answering an invite and turning down a proposed time are one metered action each. What goes to guests is an email like any other, sent from the account's own address: it passes the shared-domain daily limit, your decider (email.send, for exactly the people it reaches) and the data-flow rule, and is charged as an email. A change is stored whether or not its mail could go; the answer's notices says which left. The account's agent, the owner and an admin may use these routes.

  • GET /v1/accounts/:id/calendar/events?role&response&limit&cursor and GET .../events/:eventId - the events and invites, soonest first: role organizer (the agent's own) or attendee (an invite), start, end and time_zone as written, the repeat rule with the occurrences left out and added, changed occurrences, guests and their answers, proposed other times, the meeting room, the wake-up and the next one. What an invite says (title, place, description, guests) is written by the sender: third-party text. organizer_matches_sender is false when the organizer is not who sent the mail, and no reply is sent for such an invite.
  • GET /v1/accounts/:id/calendar/agenda?from&to&time_zone&limit&cursor - every occurrence in a range with repeats expanded and changes and cancellations applied, in a time zone. Each carries the occurrence name that changes or cancels it alone. A rule no date can meet gives no occurrences; complete is false when a rule needed more steps than one read takes.
  • POST /v1/accounts/:id/calendar/events - make an event: title, start, end, time_zone, repeat { rule, except, also }, location, meeting_link, description, guests, wake_minutes_before, meeting (a video room of STACK's, Daily in the EU, whose link goes in the invite), attend (STACK's meeting worker joins as the agent at each start and wakes it) and max_seconds. Times are a date (all day), a local time in time_zone, or an instant with Z or an offset.
  • PATCH /v1/accounts/:id/calendar/events/:eventId - change an event: the whole series, one occurrence (occurrence, as the agenda names it) or that occurrence and every one after it (scope following). Each change raises SEQUENCE. counter_id accepts a guest's proposed time with the change. An invite from someone else cannot be changed, only its wake-up.
  • POST /v1/accounts/:id/calendar/events/:eventId/cancel - cancel an event, one occurrence or it and the following; guests are mailed the cancellation. POST .../counters/:counterId/decline turns down a guest's proposed time.
  • POST /v1/accounts/:id/calendar/events/:eventId/respond - { response: accept | tentative | decline, notify_organizer? }. One metered action: it mails the organizer an iCalendar reply from the account's own address, only when the organizer is who sent the invite. A cancelled invite, or an accept of one with no readable start, is refused. An accepted invite wakes the agent before each occurrence, minus invite_lead_minutes.
  • GET, POST and DELETE /v1/accounts/:id/calendar/feed - a private read-only iCalendar URL a person adds to Google, Outlook or Apple Calendar. POST makes it or gives it a new URL (the old one stops at once) and returns it once; only a hash of its random token is kept. Whoever holds the URL sees every event and the guests' addresses until it is rotated or ended. GET /v1/calendar/feeds/:token is the feed itself.

Meetings

An event made with meeting: true has a video room of STACK's (Daily, in the EU) whose link is in the invite. The agent can be in that room: STACK's meeting worker goes in under the agent's name and only relays. STACK runs no model and says nothing of its own. The agent hears each participant by the name they gave, speaks, writes in the room's chat and leaves, through the calls below or the WebSocket. Joining is one metered action, Mission-admitted for any agent of the customer. The meeting's time is held on the account's credit ten minutes at a time and what it used (Daily's participant-minutes, Soniox's speech to text for each participant and Soniox's speech) is charged at cost when it ends. An event with attend is joined at its start and wakes the agent. What a participant says, writes or is called is a stranger's text.

  • POST /v1/accounts/:id/meetings - { event_id, max_seconds?, wait_seconds? } joins the room of one of the account's events. Returns { meeting, events } once the agent is in the room. A room the agent is in already is MEETING_ALREADY_LIVE; an event with no room is MEETING_EVENT_HAS_NO_ROOM.
  • POST /v1/accounts/:id/meetings/:meetingId/say - { text?, wait_seconds? } speaks as written, then waits for what a participant says or writes next and returns every event since your last action. POST .../chat { text } writes in the chat. POST .../leave leaves: the transcript is stored as a message and the agent woken. None of these is metered.
  • GET and PUT /v1/accounts/:id/meetings/voice - the account's meeting voice: { voice, language } (Soniox's own voice name and a language code such as fr), each null when not set. PUT sets what is given and clears what is left out; the owner, an admin or the account's own agent, not metered, no approval. STACK keeps no list of voices or languages and does not check them: Soniox's refusal is what comes back. Nothing set: Soniox's default voice, English speech and speech recognition that finds the language itself. An event can set its own with meeting_voice on POST and PATCH .../calendar/events, which replaces the account's for that event.
  • GET /v1/accounts/:id/meetings and GET .../meetings/:meetingId - the meetings, newest first, and one meeting with its transcript so far (a line the owner's controls withhold has no text).
  • GET /v1/accounts/:id/meetings/:meetingId/live (WebSocket) - every event as it happens; send { type: "text", token, last }, { type: "chat", text } and { type: "leave" }. The events are heard, chat, joined, left, paid_time_ends (the next ten minutes cannot be paid for) and ended (the reason).
Wake-ups, Calendar and Meetings | Docs