Transactional

Quickstart

Get scheduling working in 5 minutes.

Installation

TypeScript:

npm install @usetransactional/node

Python:

pip install usetransactional

Initialize the Client

TypeScript:

import { Transactional } from '@usetransactional/node';
 
const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});

Python:

from usetransactional import Transactional
 
client = Transactional(api_key="your_api_key")

Step 1: Create an Event Type

Event types define what can be booked.

TypeScript:

const eventType = await client.calendar.eventTypes.create({
  title: '30-minute Meeting',
  slug: 'meeting-30',
  duration: 30,
  description: 'A quick 30-minute meeting',
  location: {
    type: 'GOOGLE_MEET',
  },
});
 
console.log('Event Type ID:', eventType.id);
console.log('Booking URL:', eventType.bookingUrl);

Python:

event_type = client.calendar.event_types.create(
    title="30-minute Meeting",
    slug="meeting-30",
    duration=30,
    description="A quick 30-minute meeting",
    location={"type": "GOOGLE_MEET"},
)
 
print(f"Event Type ID: {event_type.id}")
print(f"Booking URL: {event_type.booking_url}")

Step 2: Set Up Availability

Define when you're available for bookings.

TypeScript:

const schedule = await client.calendar.schedules.create({
  name: 'Work Hours',
  timezone: 'America/New_York',
  isDefault: true,
  availability: [
    { day: 'MONDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'TUESDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'WEDNESDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'THURSDAY', startTime: '09:00', endTime: '17:00' },
    { day: 'FRIDAY', startTime: '09:00', endTime: '17:00' },
  ],
});
 
// Link schedule to event type
await client.calendar.eventTypes.update(eventType.id, {
  scheduleId: schedule.id,
});

Python:

schedule = client.calendar.schedules.create(
    name="Work Hours",
    timezone="America/New_York",
    is_default=True,
    availability=[
        {"day": "MONDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "TUESDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "WEDNESDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "THURSDAY", "startTime": "09:00", "endTime": "17:00"},
        {"day": "FRIDAY", "startTime": "09:00", "endTime": "17:00"},
    ],
)
 
# Link schedule to event type
client.calendar.event_types.update(
    event_type.id,
    schedule_id=schedule.id
)

Step 3: Get Available Slots

Query available times for booking.

TypeScript:

const availability = await client.calendar.availability.get({
  eventTypeId: eventType.id,
  startDate: '2024-01-15',
  endDate: '2024-01-22',
  timezone: 'America/New_York',
});
 
console.log('Available slots:');
for (const day of availability.days) {
  console.log(`${day.date}:`);
  for (const slot of day.slots) {
    console.log(`  ${slot.startTime} - ${slot.endTime}`);
  }
}

Python:

availability = client.calendar.availability.get(
    event_type_id=event_type.id,
    start_date="2024-01-15",
    end_date="2024-01-22",
    timezone="America/New_York",
)
 
print("Available slots:")
for day in availability.days:
    print(f"{day.date}:")
    for slot in day.slots:
        print(f"  {slot.start_time} - {slot.end_time}")

Step 4: Create a Booking

Book an available time slot.

TypeScript:

const booking = await client.calendar.bookings.create({
  eventTypeId: eventType.id,
  startTime: '2024-01-15T10:00:00-05:00',
  attendee: {
    name: 'John Doe',
    email: 'john@example.com',
    timezone: 'America/New_York',
  },
  notes: 'Looking forward to the meeting!',
});
 
console.log('Booking confirmed!');
console.log('UID:', booking.uid);
console.log('Start:', booking.startTime);
console.log('End:', booking.endTime);
console.log('Meeting URL:', booking.meetingUrl);

Python:

booking = client.calendar.bookings.create(
    event_type_id=event_type.id,
    start_time="2024-01-15T10:00:00-05:00",
    attendee={
        "name": "John Doe",
        "email": "john@example.com",
        "timezone": "America/New_York",
    },
    notes="Looking forward to the meeting!",
)
 
print("Booking confirmed!")
print(f"UID: {booking.uid}")
print(f"Start: {booking.start_time}")
print(f"End: {booking.end_time}")
print(f"Meeting URL: {booking.meeting_url}")

Step 5: Handle Webhooks

Set up webhooks to receive booking notifications.

TypeScript:

// Create webhook subscription
const webhook = await client.calendar.webhooks.create({
  url: 'https://yourapp.com/webhooks/calendar',
  events: [
    'booking.created',
    'booking.cancelled',
    'booking.rescheduled',
  ],
});
 
console.log('Webhook secret:', webhook.secret);

Express handler:

app.post('/webhooks/calendar', (req, res) => {
  const event = req.body;
 
  switch (event.type) {
    case 'booking.created':
      console.log('New booking:', event.data.booking);
      // Send confirmation, update CRM, etc.
      break;
 
    case 'booking.cancelled':
      console.log('Booking cancelled:', event.data.booking);
      // Free up resources, notify team, etc.
      break;
 
    case 'booking.rescheduled':
      console.log('Booking rescheduled:', event.data.booking);
      // Update records, notify attendees, etc.
      break;
  }
 
  res.status(200).send('OK');
});

Complete Example

Here's a full working example:

TypeScript:

import { Transactional } from '@usetransactional/node';
 
const client = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
async function setupScheduling() {
  // Create event type
  const eventType = await client.calendar.eventTypes.create({
    title: 'Product Demo',
    slug: 'demo',
    duration: 45,
    description: 'See our product in action',
    location: { type: 'ZOOM' },
    requiresConfirmation: false,
    bufferBefore: 5,
    bufferAfter: 10,
  });
 
  // Create schedule
  const schedule = await client.calendar.schedules.create({
    name: 'Demo Hours',
    timezone: 'America/New_York',
    isDefault: true,
    availability: [
      { day: 'TUESDAY', startTime: '10:00', endTime: '16:00' },
      { day: 'WEDNESDAY', startTime: '10:00', endTime: '16:00' },
      { day: 'THURSDAY', startTime: '10:00', endTime: '16:00' },
    ],
  });
 
  // Link schedule
  await client.calendar.eventTypes.update(eventType.id, {
    scheduleId: schedule.id,
  });
 
  // Get availability for next week
  const today = new Date();
  const nextWeek = new Date(today.getTime() + 7 * 24 * 60 * 60 * 1000);
 
  const availability = await client.calendar.availability.get({
    eventTypeId: eventType.id,
    startDate: today.toISOString().split('T')[0],
    endDate: nextWeek.toISOString().split('T')[0],
  });
 
  console.log('Setup complete!');
  console.log('Booking URL:', eventType.bookingUrl);
  console.log('Available slots:', availability.days.flatMap(d => d.slots).length);
}
 
setupScheduling();

Embed Booking Widget

Add the booking widget to your website:

<!-- Add to your HTML -->
<div id="transactional-booking"></div>
 
<script src="https://cdn.usetransactional.com/sdk/calendar.min.js"></script>
<script>
  TransactionalCalendar.init({
    elementId: 'transactional-booking',
    eventTypeSlug: 'demo',
    organizationSlug: 'your-org',
    theme: 'light',
  });
</script>

Or with React:

import { CalendarEmbed } from '@usetransactional/react';
 
function BookingPage() {
  return (
    <CalendarEmbed
      eventTypeSlug="demo"
      organizationSlug="your-org"
      onBookingComplete={(booking) => {
        console.log('Booking complete:', booking);
      }}
    />
  );
}

Next Steps