# Integration contracts and activation requirements ## Webchat adapter The current release tests an HTTPS API adapter, not arbitrary embedded widgets. An operator must allow the exact hostname in `AGENT_ALLOWED_HOSTS`. Redirects, plaintext HTTP, embedded URL credentials, local IP literals, and unapproved hosts are rejected. Set a per-agent server secret such as `TW_JUNIPER_AGENT_TOKEN`; the browser stores only the secret name. Request: POST the configured endpoint with a bearer token and JSON: ```json {"sessionId":"tapewall-RUN_UUID","testMode":true,"runId":"tapewall-RUN_UUID","seed":1042,"message":"Customer turn","history":[{"role":"customer","text":"Customer turn"}],"calendarId":"DEDICATED_TEST_CALENDAR"} ``` Response: ```json {"reply":"Agent response","bookingClaimed":true} ``` `bookingClaimed` is a claim, never the source of booking truth. Maximum eight scripted customer turns. Optional branchRules select the next message by a case-insensitive phrase in the preceding agent reply; the first match wins, otherwise the fixed message is used. Configure complete scenarios and explicitly expected calendar values. An optional structured-output OpenAI judge is implemented but inactive. See OPERATIONS.md for consent, reserve and human-review gates. ## Google Calendar Reader: GET `https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events`. The integration requires a dedicated non-primary test calendar and a bearer access token with read-only event permission. Calendar-bound OAuth refresh is implemented for operator-configured grants, but the deployed application grant and a real-agent workflow remain unvalidated. Self-service OAuth is not available. Primary calendars are prohibited. The test agent or trusted adapter must put the following in the event's private extended properties: `tapewallRunId`, `service`, `staff`, `customer`, `customerEmail`. `tapewallRunId` must equal the exact runId sent by Tapewall. The event start and end must be real ISO date-time values. The reader filters by the run identifier, paginates, and treats pagination exhaustion as incomplete evidence. IMPORTANT: prove the tagging contract with a known test event before activation. Untagged events cannot be detected by this reader. Run identifiers isolate test evidence; they do not prove production safety by themselves. Official references checked October 19, 2026: - https://developers.google.com/workspace/calendar/api/v3/reference/events - https://developers.google.com/calendar/api/v3/reference/events/list ## Cal.com Reader: GET `https://api.cal.com/v2/bookings` with `cal-api-version: 2026-05-01`. The configured ID is the dedicated test event type ID. Use a test-account token with BOOKING_READ when using OAuth. Bookings must include `metadata.tapewallRunId`; `metadata.service` is preferred over the booking title. Hosts and attendees supply staff and customer fields. Pagination uses the provider limit parameter with bounded pages; incomplete results route to review. Verify field mappings against the actual account before activation. Reference rechecked October 20, 2026 UTC: https://cal.com/docs/api-reference/v2/bookings/get-all-bookings. Only accepted bookings normalize to confirmed; pending or rejected records cannot pass confirmation checks. ## Fixture preparation and cleanup Calendar readers remain read-only. Fixture and cleanup work uses a separately authorized test-control endpoint on an operator-allowed host. This is required before live booking, rescheduling, or cancellation scenarios; information-only scenarios can omit it. The agency must explicitly authorize its use. Request: ```json {"action":"prepare","testMode":true,"runId":"tapewall-RUN_UUID","calendarId":"TEST_ONLY","expected":{"action":"cancel"},"fixture":null} ``` The endpoint must return `{ "ok": true, "testMode": true, "runId": "tapewall-RUN_UUID" }`. For cancellation and rescheduling, prepare creates the existing tagged fixture before Tapewall takes the baseline snapshot. Cleanup uses the same contract with action `cleanup` after evidence capture. It must delete only events owned by this synthetic test run. It must not accept arbitrary calendar identifiers without its own allowlist. Tapewall does not grant this endpoint access to production calendars. No authorized cleanup endpoint means booking scenarios are blocked before quota reservation. Fixture creation and cleanup require integration contract tests and account authorization, not just a checkbox. Cleanup acknowledgments are currently trusted adapter evidence; independent verification of deletion and provider consistency retries remain outstanding. ## Twilio voice The adapter uses Calls API, dual-channel recording, scripted Say/Gather turns, completed-call callbacks, and HMAC-SHA1 request validation. Runtime gates: `LIVE_TESTS_ENABLED=true` and `VOICE_CALLBACKS_ENABLED=true`. Required settings: `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_FROM_NUMBER`, `TWILIO_TEST_NUMBERS` (exact allowed test recipients), and `VOICE_PUBLIC_ORIGIN`. A private Sites deployment cannot receive unauthenticated Twilio callbacks through its sign-in wall. Voice activation therefore requires a publicly reachable callback deployment with the signature validation preserved. Do not weaken authentication on the private application just to make callbacks work. The callback origin must route to the same voice-state store. The architecture and this live integration are not yet validated. Each configured recipient needs agency authorization for automated testing and recording. The adapter enforces a 30 to 180 second call limit, with a 120 second default. No phone calls were placed during development. Speech recognition provides the remote speech transcript; synthesized customer lines are recorded from the script. This is not a full acoustic evaluator for interruption, emotion, or silence quality. Recordings remain with Twilio and require account-level retention settings. References: - https://www.twilio.com/docs/voice/api/call-resource - https://www.twilio.com/docs/voice/twiml/gather - https://www.twilio.com/docs/usage/security ## Payments and alerts Optional `STRIPE_PILOT_PAYMENT_LINK` can link to an operator-created Stripe payment page after compatibility review. Subscription creation, payment webhooks, invoices, and entitlements are not implemented. No Stripe account was connected. No Slack or email messages are sent. Morning reports can be downloaded as Markdown; CSV evidence exports are available.