Provisioning and onboarding
These examples build on the quickstart. They use the same Bright Smile Dental customer, and every workspace call carries its ID in xi-workspace-id.
Provision workspaces
Provision in one request
When you don’t have the business details yet, create the workspace, subscribe it, invite the owner and finish onboarding in one call. The receptionist is built from the business name alone, so fill in the business profile afterwards. Pass an idempotency_key so a retry after a timeout can’t create a second workspace.
Onboarding at creation is best-effort: if it fails, onboarding_completed_at_unix is null and you can retry it with complete_onboarding.
Provision customers from your CRM
Derive each idempotency_key from your own customer ID, so running the import again returns the workspaces it already created instead of creating new ones. The same key with a different body is rejected with idempotency_key_reused.
Finish onboarding for workspaces still in setup
workspaces.list shows which workspaces haven’t finished onboarding. complete_onboarding is safe to retry, so you can run this on a schedule.
Describe the business
Add the business’s locations, staff, services and closures before you complete onboarding, so the receptionist is built from them. You can add or change them at any time after that too.
Until onboarding is complete, the setup wizard the business owner sees when they sign in can replace or remove this data. Complete onboarding before the owner signs in.
Add a location
Each location has its own hours. Days run from 0 (Monday) to 6 (Sunday), and a day with no entry is closed.
Add a staff member
A staff member at a location follows that location’s hours unless you give them their own working_hours. customer_facing_name is what callers hear; name stays the internal label.
Add services
A service has one or more variants, each with its own length and price; the first is the default. Set any_staff_member to false to limit who can deliver it.
When the price depends on the job, use pricing_mode="quote" and add intake_questions. The receptionist asks them and takes a quote request instead of quoting a price.
Close for a holiday
A closure covers whole days, from start_date to end_date. Use time_off_type="location" for the business, or "staff" with the staff member’s ID in resource_id for one person’s time off.
Upload a document
Give the receptionist a document to answer from, such as an FAQ or a price list. Use knowledge_sources.add_url for a website, as in the quickstart.
Set up the receptionist
These calls need the receptionist’s ID: customer_facing_agent_id from complete_onboarding, or agent_id from receptionists.list.
Set the greeting, languages and what to collect
Only the settings you send change.
Transfer calls and add rules
A transfer rule hands the call to a person when its condition is met. Transfers depend on the plan: check is_transfer_allowed on the receptionist first. A rule tells the receptionist how to behave; a strict rule is always followed, a suggestion is a guideline.
Invite the team
Invite people at any time after the workspace exists. A pending invite takes a seat, so an invite is refused once members and invites reach the plan’s team size.