Integrations, APIs and Custom Extensions
What this domain tests
This domain tests connecting the assistant to external systems and embedding it in applications. Expect questions on channels, custom extensions, OpenAPI schemas, authentication, session APIs and error handling.
Core rules
- Channels are where users meet the assistant: web chat, messaging, voice and custom applications. Extensions are how the assistant calls backend services.
- A custom extension is described by an OpenAPI document. Operation IDs, request schemas and response schemas must match what the action expects.
- Keep credentials server-side. Store environment-specific secrets in the assistant’s secure configuration, not in browser code or session variables.
- For custom clients, create a session, send messages to that session, and delete it when done. Reusing a session preserves context; starting a new one resets it.
- Handle non-2xx responses, timeouts and schema drift with explicit error branches. Do not let a raw backend error reach the user.
- Design idempotent operations for retries, especially payments, cancellations and case creation.
Worked example
An action calls getOrderStatus. The OpenAPI operation takes order_id as a path parameter and returns status and eta. The action maps the user’s order number to order_id, calls the extension, and branches on status. If the extension returns 404, the action says the order was not found and asks for a retry; if it returns 500, it apologizes and offers an agent. Reasoning: each status has a different user meaning, and retry behavior must not create duplicate side effects.
Traps
Confusing a channel with an extension; hard-coding API keys in the web chat snippet; ignoring schema mismatches until runtime; forgetting to close sessions; and retrying a non-idempotent POST blindly.