Component: scheduling_embed

scheduling_embed renders your Calendly booking page inside the conversation. The user books a slot in the real widget, and the confirmed booking is reported to the PAL and delivered to your webhook as a canvas.interaction event. See Enabling and configuring components for skill attachment and general component settings.

Configuration

Attaching the skill alone does not activate scheduling_embed. It stays inactive (no action is compiled, no error) until a valid scheduling_url is saved in the skill config.

curl -X PUT https://tavusapi.com/v2/pals/{pal_id}/skills/magic_canvas \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "config": {
      "components": {
        "scheduling_embed": {
          "provider": "calendly",
          "scheduling_url": "https://calendly.com/your-team/30min"
        }
      }
    }
  }'

Field	Type	Required	Description
`provider`	string	❌	Defaults to `"calendly"`, the only supported provider.
`scheduling_url`	string	✅	Your HTTPS booking link, max 2048 characters (enforced when you save the config). The component activates as soon as a valid value is saved.
`enabled`	boolean	❌	Defaults to `true`. Set `false` to switch the component off without deleting your link config.

scheduling_url is validated on save: it must start with https://, be at most 2048 characters, and not point at localhost, cloud metadata hostnames, or private, loopback, link-local, or reserved IPs. No DNS resolution is performed, so other non-public hostnames can pass. The renderer also requires a calendly.com or *.calendly.com host; otherwise the card renders a “Scheduling not configured” panel.

Arguments

The PAL invokes canvas_show_scheduling_embed when the user should book a meeting and a scheduling link is configured. The booking link itself is never an argument.

Field	Type	Required	Description
`title`	string	❌	Heading shown above the embed. 1–160 characters.
`prefill`	object	❌	Pre-populates the booking form. No extra keys allowed.
`prefill.name`	string	❌	Invitee name, filled into the widget. Up to 160 characters.
`prefill.email`	string	❌	Invitee email, filled into the widget. Up to 254 characters.

{
  "title": "Book a time",
  "prefill": {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }
}

The runtime attaches a layout (preferred_slot) control. scheduling_embed renders inline in a side rail (default safe-area-right; the model may pick safe-area-left or safe-area-right) and supports live updates via update_component.

There is no url, link, or scheduling_url argument. The link comes from your PAL config, delivered directly to the sandboxed renderer, bypassing the model entirely.

Interactions

The built-in card emits exactly one interaction type: submit, sent when the user completes a booking. There is no close control, so closing the card without booking produces no interaction. Renderer failures surface as an in-card “Scheduling unavailable” panel, not as webhooks.

The interactions API also accepts skip, dismiss, clear, error, and heartbeat for this component, for custom clients that post their own interactions; these are not shape-validated by Tavus.

`submit`

The value object accepts only these keys:

Field	Type	Required	Description
`provider`	string	✅	Always `"calendly"`.
`scheduled`	boolean	✅	Always `true`; a submit only fires on a confirmed booking.
`event_uri`	string	❌	Calendly API resource URI (HTTPS, `calendly.com` or `*.calendly.com` host). Use with the Calendly API to fetch the meeting time, invitee answers, and cancellation links; Tavus passes it through without fetching it.
`invitee_uri`	string	❌	Calendly API resource URI (HTTPS, `calendly.com` or `*.calendly.com` host). Passed through without being fetched.

Example webhook for a completed booking:

{
  "message_type": "canvas",
  "event_type": "canvas.interaction",
  "properties": {
    "conversation_id": "c7f8a1b2c3d4",
    "interaction_id": "ci_call_9d41f2_submit_6f1c9a2e-3b7d-4e8a-9c01-5a2b8d7e4f10",
    "tool_call_id": "call_9d41f2",
    "component": "canvas.scheduling_embed",
    "component_version": "v1",
    "type": "submit",
    "value": {
      "provider": "calendly",
      "scheduled": true,
      "event_uri": "https://api.calendly.com/scheduled_events/GBGBDCAADAEDCRZ2",
      "invitee_uri": "https://api.calendly.com/scheduled_events/GBGBDCAADAEDCRZ2/invitees/AAAAAAAAAAAAAAAA"
    },
    "metadata": {
      "client_timestamp": "2026-06-09T18:42:11.000Z"
    },
    "created_at": "2026-06-09T18:42:11.123456"
  }
}

created_at is a naive ISO-8601 timestamp with microsecond precision and no timezone suffix. The canvas.interaction webhook fires once per interaction. Fetch the full history at any time:

curl https://tavusapi.com/v2/conversations/{conversation_id}/canvas/interactions \
  -H "x-api-key: <your-api-key>"

When to Use

Use scheduling_embed when booking a meeting is a goal of the conversation. The user books in your real Calendly page, so availability, routing, and confirmation emails work as they do on your website. For a date or time preference without a real booking, use calendar instead.

​Configuration

​Arguments

​Interactions

​submit

​When to Use

Configuration

Arguments

Interactions

`submit`

When to Use