# Sitebot Integration

## When to use

Use this skill when an organization needs its AgentsHQ (AI agent orchestration platform) automation to provision Sitebot (conversational AI agent) accounts, sync users between systems, or manage Sitebot's scheduling (booking/calendar) resources on behalf of a customer or lead. Typical triggers: a new organization signs up and needs a Sitebot workspace, a lead needs to be turned into a Sitebot user, or a downstream flow needs to check, create, update, or cancel a scheduling event inside Sitebot.

## Tools

- `http-get` — read organizations, users, or scheduling data from Sitebot's REST API
- `http-post` — create organizations, users, scheduling events, event types, or availability rules
- `http-request` — update or delete existing scheduling events (PUT/PATCH/DELETE)
- `write-file` — stage large result sets (e.g. bulk event or availability listings) instead of dumping them inline
- `send-message` — escalate to a human when authentication fails or an Integration is missing

All calls target the base URL configured in the org's Integration row for Sitebot (e.g. `https://sitebot.newx.app/api/...`). Credentials (bearer token or API key) are injected automatically by the Integration row — never request, print, or hardcode them.

## Playbook

1. To create or fetch an organization in Sitebot, call `http-post` against `/api/v1/organizations`, optionally including a user to create/find alongside it. This endpoint is idempotent by slug/name — safe to call even if the organization may already exist.
2. To onboard a new user under that organization, call `http-post` against `/api/users`. This kicks off async setup of the user's chatbot/web channel — do not assume the channel is ready immediately after the response returns.
3. Before creating a user, check whether one already exists by calling `http-get` on `/api/users/find_by_email` with the email address. If found, use `http-get` on `/api/users/:id` to fetch full details instead of creating a duplicate.
4. To list a resource's booking slots or check availability, call `http-get` on `/api/scheduling/availabilities`, `/api/scheduling/availabilities/check_slot`, or `/api/scheduling/availabilities/formatted` depending on whether you need raw rules, a single slot check, or a display-ready range.
5. To see what meeting types exist before booking, call `http-get` on `/api/scheduling/event_types`, optionally filtered by `resource_id`.
6. To book a meeting, call `http-post` on `/api/scheduling/events` with customer, resource, event_type, and date/time. To review existing bookings, call `http-get` on `/api/scheduling/events` or `/api/scheduling/events/:id`.
7. To reschedule or cancel a booking, use `http-request` with PUT on `/api/scheduling/events/:id` to update it, or DELETE on the same path to remove it.
8. If a step returns a large list (many events, users, or availability slots), use `write-file` to stage the full payload rather than inlining it in your response, and summarize the key entries instead.
9. If any call is needed but no Integration row exists for Sitebot, or a call returns 401/403, stop immediately and use `send-message` to escalate to a human, naming "Sitebot" and the specific scope required (e.g. write access for organizations, or a valid API key for user endpoints).

## Failure modes

- Missing Integration row for Sitebot: do not guess a base URL — escalate via `send-message`.
- 401/403 on any call: the token or key is invalid, expired, or lacks the required scope (write scope is required for mutating scheduling calls). Stop and escalate; do not retry with fabricated credentials.
- Duplicate user creation: always check `/api/users/find_by_email` first to avoid creating redundant users.
- Async setup lag: a freshly created user's chatbot/web channel may not be immediately queryable; do not treat a missing channel right after creation as an error.
- Slot conflicts: a `POST /api/scheduling/events` may fail if the slot is no longer available — re-check with `/api/scheduling/availabilities/check_slot` before retrying.

## Done when

The requested organization, user, or scheduling record exists (or is confirmed absent) in Sitebot, all mutating calls have returned success responses, any large result sets have been staged with `write-file`, and no unresolved authentication or missing-Integration condition remains unescalated.