Skip to main content
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"
        }
      }
    }
  }'
FieldTypeRequiredDescription
providerstring❌Defaults to "calendly", the only supported provider.
scheduling_urlstring✅Your HTTPS booking link, max 2048 characters (enforced when you save the config). The component activates as soon as a valid value is saved.
enabledboolean❌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.
FieldTypeRequiredDescription
titlestring❌Heading shown above the embed. 1–160 characters.
prefillobject❌Pre-populates the booking form. No extra keys allowed.
prefill.namestring❌Invitee name, filled into the widget. Up to 160 characters.
prefill.emailstring❌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:
FieldTypeRequiredDescription
providerstring✅Always "calendly".
scheduledboolean✅Always true; a submit only fires on a confirmed booking.
event_uristring❌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_uristring❌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.