วิธีใช้ Calendly API: คู่มือสำหรับนักพัฒนาเพื่อการผสานรวมการนัดหมาย

TL;DR

Calendly APIs ให้คุณทำเวิร์กโฟลว์การตั้งเวลาอัตโนมัติ คุณรับรองความถูกต้องด้วย OAuth 2.0 เข้าถึงประเภทกิจกรรมและการจองผ่าน api.calendly.com และรับการอัปเดตแบบเรียลไทม์ผ่านเว็บฮุก สำหรับการทดสอบ ให้ใช้ Apidog เพื่อตรวจสอบเพย์โหลดเว็บฮุกและทดสอบการผสานรวมของคุณโดยไม่ต้องสร้างการจองจริง

บทนำ

Calendly ประมวลผลการประชุมหลายล้านครั้งต่อเดือน ผู้คนใช้สำหรับสายการขาย เซสชันสนับสนุน การปรึกษาหารือ และการสัมภาษณ์ API ช่วยให้คุณสามารถฝังความสามารถในการตั้งเวลานั้นลงในแอปของคุณเองได้

รูปแบบทั่วไป: คุณต้องการให้การจอง Calendly ทริกเกอร์การดำเนินการในระบบของคุณ ผู้ใช้จองการสาธิต และ CRM ของคุณได้รับการอัปเดต มีการกำหนดเวลาการปรึกษาหารือ และคุณส่งแบบสอบถาม การประชุมถูกยกเลิก และคุณแจ้งทีมของคุณ

API ของ Calendly จัดการสิ่งนี้ผ่านเว็บฮุก เมื่อมีเหตุการณ์เกิดขึ้น (การจองถูกสร้างขึ้น ยกเลิก หรือกำหนดเวลาใหม่) Calendly จะ POST ไปยังปลายทางของคุณ คุณประมวลผลเพย์โหลดและดำเนินการ

การรับรองความถูกต้องด้วย OAuth 2.0

Calendly ใช้ OAuth 2.0 สำหรับการเข้าถึง API คุณไม่สามารถใช้เพียงแค่ API key ได้

สร้างแอปพลิเคชัน OAuth

1. ไปที่ Calendly → Integrations → API & Webhooks
2. คลิก “Create New Application”
3. ตั้งค่า Redirect URI ของคุณ (เช่น https://yourapp.com/auth/calendly/callback)
4. รับ Client ID และ Client Secret ของคุณ

ขั้นตอนการทำงานของ OAuth

ขั้นตอนที่ 1: เปลี่ยนเส้นทางผู้ใช้เพื่ออนุมัติ

https://auth.calendly.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=https://yourapp.com/auth/calendly/callback

ขั้นตอนที่ 2: ผู้ใช้อนุมัติและถูกเปลี่ยนเส้นทางกลับ

https://yourapp.com/auth/calendly/callback?code=AUTHORIZATION_CODE

ขั้นตอนที่ 3: แลกเปลี่ยนโค้ดสำหรับโทเค็นการเข้าถึง

const response = await fetch('https://auth.calendly.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(clientId + ':' + clientSecret).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authCode,
    redirect_uri: 'https://yourapp.com/auth/calendly/callback'
  })
})

const { access_token, refresh_token, expires_in } = await response.json()

ขั้นตอนที่ 4: ใช้โทเค็น

curl -X GET "https://api.calendly.com/users/me" \
  -H "Authorization: Bearer ACCESS_TOKEN"

รีเฟรชโทเค็น

โทเค็นการเข้าถึงจะหมดอายุหลังจาก 2 ชั่วโมง ใช้รีเฟรชโทเค็นเพื่อรับโทเค็นใหม่:

const response = await fetch('https://auth.calendly.com/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + Buffer.from(clientId + ':' + clientSecret).toString('base64')
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken
  })
})

การรับข้อมูลผู้ใช้

รับผู้ใช้ปัจจุบัน

curl -X GET "https://api.calendly.com/users/me" \
  -H "Authorization: Bearer ACCESS_TOKEN"

การตอบสนอง:

{
  "resource": {
    "avatar_url": "https://calendly.com/avatar.jpg",
    "created_at": "2024-01-15T10:00:00Z",
    "current_organization": "https://api.calendly.com/organizations/ABC123",
    "email": "you@example.com",
    "name": "John Doe",
    "scheduling_url": "https://calendly.com/johndoe",
    "slug": "johndoe",
    "timezone": "America/New_York",
    "uri": "https://api.calendly.com/users/ABC123"
  }
}

รับสมาชิกองค์กร

curl -X GET "https://api.calendly.com/organization_memberships/me" \
  -H "Authorization: Bearer ACCESS_TOKEN"

ประเภทกิจกรรม

ประเภทกิจกรรมคือเทมเพลตการประชุมที่ผู้ใช้สร้างขึ้น (การโทร 30 นาที, การปรึกษา 60 นาที ฯลฯ)

รายการประเภทกิจกรรม

curl -X GET "https://api.calendly.com/event_types?user=https://api.calendly.com/users/ABC123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

การตอบสนอง:

{
  "resource": {
    "uri": "https://api.calendly.com/event_types/ETC123",
    "active": true,
    "booking_method": "instant",
    "color": "#0066FF",
    "created_at": "2024-01-15T10:00:00Z",
    "description_html": "<p>ปรึกษา 30 นาที</p>",
    "duration": 30,
    "internal_note": "ใช้ลิงก์ Zoom",
    "kind": "solo",
    "name": "ปรึกษา 30 นาที",
    "pooling_type": null,
    "profile": {
      "name": "John Doe",
      "type": "User",
      "owner": "https://api.calendly.com/users/ABC123"
    },
    "scheduling_url": "https://calendly.com/johndoe/30min",
    "slug": "30min",
    "type": "StandardEventType"
  },
  "pagination": {
    "count": 1,
    "next_page": null
  }
}

รับประเภทกิจกรรมที่เฉพาะเจาะจง

curl -X GET "https://api.calendly.com/event_types/ETC123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

กิจกรรมที่กำหนดเวลาไว้ (การจอง)

กิจกรรมคือการจองจริงที่ทำผ่าน Calendly

รายการกิจกรรมที่กำหนดเวลาไว้

curl -X GET "https://api.calendly.com/scheduled_events?user=https://api.calendly.com/users/ABC123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

กรองตามช่วงวันที่:

curl -X GET "https://api.calendly.com/scheduled_events?min_start_time=2026-03-01T00:00:00Z&max_start_time=2026-03-31T23:59:59Z" \
  -H "Authorization: Bearer ACCESS_TOKEN"

การตอบสนอง:

{
  "resource": {
    "uri": "https://api.calendly.com/scheduled_events/ABC123",
    "status": "active",
    "tracking": {
      "utm_campaign": "spring_sale",
      "utm_source": "email",
      "utm_medium": "newsletter"
    },
    "created_at": "2026-03-24T10:00:00Z",
    "end_time": "2026-03-25T11:00:00Z",
    "event_type": "https://api.calendly.com/event_types/ETC123",
    "invitees_counter": {
      "active": 1,
      "limit": 1,
      "total": 1
    },
    "location": {
      "type": "zoom",
      "join_url": "https://zoom.us/j/123456789"
    },
    "start_time": "2026-03-25T10:30:00Z",
    "updated_at": "2026-03-24T10:00:00Z"
  }
}

รับรายละเอียดกิจกรรม

curl -X GET "https://api.calendly.com/scheduled_events/EVENT_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

รับผู้เข้าร่วมสำหรับกิจกรรม

curl -X GET "https://api.calendly.com/scheduled_events/EVENT_ID/invitees" \
  -H "Authorization: Bearer ACCESS_TOKEN"

การตอบสนอง:

{
  "resource": [
    {
      "cancel_url": "https://calendly.com/cancellations/ABC123",
      "created_at": "2026-03-24T10:00:00Z",
      "email": "jane@example.com",
      "event": "https://api.calendly.com/scheduled_events/ABC123",
      "name": "Jane Smith",
      "new_invitee": null,
      "old_invitee": null,
      "reschedule_url": "https://calendly.com/reschedulings/ABC123",
      "status": "active",
      "text_reminder_number": "+15551234567",
      "timezone": "America/New_York",
      "tracking": {
        "utm_campaign": null,
        "utm_source": null
      },
      "updated_at": "2026-03-24T10:00:00Z",
      "uri": "https://api.calendly.com/scheduled_event_invitees/INV123",
      "canceled": null
    }
  ]
}

เว็บฮุกสำหรับการอัปเดตแบบเรียลไทม์

เว็บฮุกจะแจ้งเตือนแอปของคุณเกี่ยวกับกิจกรรมการจองแบบเรียลไทม์

สร้างการสมัครสมาชิกเว็บฮุก

curl -X POST "https://api.calendly.com/webhook_subscriptions" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/calendly",
    "events": [
      "invitee.created",
      "invitee.canceled",
      "invitee.rescheduled"
    ],
    "organization": "https://api.calendly.com/organizations/ORG123",
    "scope": "organization"
  }'

กิจกรรมที่ใช้งานได้:

• invitee.created - สร้างการจองใหม่
• invitee.canceled - ยกเลิกการจอง
• invitee.rescheduled - กำหนดเวลาการจองใหม่

รายการการสมัครสมาชิกเว็บฮุก

curl -X GET "https://api.calendly.com/webhook_subscriptions?organization=https://api.calendly.com/organizations/ORG123" \
  -H "Authorization: Bearer ACCESS_TOKEN"

ลบเว็บฮุก

curl -X DELETE "https://api.calendly.com/webhook_subscriptions/WEBHOOK_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN"

การจัดการเพย์โหลดเว็บฮุก

ตรวจสอบลายเซ็นเว็บฮุก

Calendly ลงนามเว็บฮุกด้วยลายเซ็นในส่วนหัว Calendly-Webhook-Signature:

import crypto from 'crypto'

function verifySignature(payload, signature, secret) {
  const [t, v1] = signature.split(',')
  const timestamp = t.split('=')[1]
  const hash = v1.split('=')[1]
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + payload)
    .digest('hex')
  
  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/calendly', (req, res) => {
  const signature = req.headers['calendly-webhook-signature']
  const payload = JSON.stringify(req.body)
  
  if (!verifySignature(payload, signature, process.env.CALENDLY_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }
  
  // Process webhook
  handleWebhook(req.body)
  res.status(200).send('OK')
})

ประมวลผลกิจกรรมการจอง

function handleWebhook(payload) {
  const { event, payload: data } = payload
  
  switch (event) {
    case 'invitee.created':
      console.log(`การจองใหม่: ${data.event.start_time}`)
      console.log(`ผู้เข้าร่วม: ${data.email}`)
      // เพิ่มลงใน CRM, ส่งอีเมลยืนยัน ฯลฯ
      syncToCRM(data)
      break
      
    case 'invitee.canceled':
      console.log(`ยกเลิกการจอง: ${data.event.uri}`)
      // อัปเดต CRM, แจ้งทีม ฯลฯ
      removeFromCRM(data)
      break
      
    case 'invitee.rescheduled':
      console.log(`กำหนดเวลาการจองใหม่: ${data.event.start_time}`)
      // อัปเดตปฏิทิน, แจ้งทีม ฯลฯ
      updateCRM(data)
      break
  }
}

การทดสอบด้วย Apidog

API ของ Calendly ต้องใช้ OAuth ซึ่งทำให้การทดสอบซับซ้อน Apidog ทำให้สิ่งนี้ง่ายขึ้น

1. จำลองการตอบสนองของ OAuth

ในระหว่างการพัฒนา ไม่จำเป็นต้องดำเนินการตามขั้นตอน OAuth ทั้งหมดทุกครั้ง จำลองการตอบสนองโทเค็น:

{
  "access_token": "mock_access_token",
  "refresh_token": "mock_refresh_token",
  "expires_in": 7200,
  "created_at": 1700000000
}

2. ทดสอบตัวจัดการเว็บฮุก

สร้างเพย์โหลดเว็บฮุกจำลอง:

{
  "created_at": "2026-03-24T10:00:00Z",
  "event": "invitee.created",
  "payload": {
    "email": "test@example.com",
    "name": "Test User",
    "event": {
      "start_time": "2026-03-25T10:30:00Z",
      "end_time": "2026-03-25T11:00:00Z",
      "event_type": {
        "name": "30 Min Consultation"
      }
    }
  }
}

ส่งไปยังปลายทางเว็บฮุกของคุณและตรวจสอบการจัดการ

3. ตัวแปรสภาพแวดล้อม

CALENDLY_CLIENT_ID: abc123
CALENDLY_CLIENT_SECRET: xyz789
CALENDLY_ACCESS_TOKEN: stored_token
CALENDLY_REFRESH_TOKEN: stored_refresh
CALENDLY_WEBHOOK_SECRET: webhook_signing_secret

4. ตรวจสอบลายเซ็นเว็บฮุก

pm.test('Webhook signature is valid', () => {
  const signature = pm.request.headers.get('Calendly-Webhook-Signature')
  pm.expect(signature).to.exist
  
  const payload = pm.request.body.raw
  const secret = pm.environment.get('CALENDLY_WEBHOOK_SECRET')
  
  // Verify signature
  const valid = verifySignature(payload, signature, secret)
  pm.expect(valid).to.be.true
})

ทดสอบเว็บฮุก Calendly ด้วย Apidog - ฟรี

ข้อผิดพลาดทั่วไปและการแก้ไข

401 ไม่ได้รับอนุญาต

สาเหตุ: โทเค็นไม่ถูกต้องหรือหมดอายุ

วิธีแก้ไข:

1. ตรวจสอบโทเค็นว่ายังไม่หมดอายุ (หมดอายุ 2 ชั่วโมง)
2. ใช้รีเฟรชโทเค็นเพื่อรับโทเค็นการเข้าถึงใหม่
3. ตรวจสอบให้แน่ใจว่าส่วนหัว Authorization คือ Bearer {token}

403 ห้ามเข้าถึง

สาเหตุ: ขอบเขต OAuth ไม่เพียงพอ

วิธีแก้ไข: โทเค็น OAuth ต้องการขอบเขตที่เหมาะสม เมื่อร้องขอการอนุญาต ให้รวมขอบเขตที่จำเป็น ขอบเขตของ Calendly เป็นแบบโดยนัยตามที่ผู้ใช้อนุญาต

404 ไม่พบ

สาเหตุ: ทรัพยากรไม่มีอยู่จริงหรือผู้ใช้ไม่มีสิทธิ์เข้าถึง

วิธีแก้ไข:

1. ตรวจสอบ URI ของทรัพยากรว่าถูกต้อง
2. ตรวจสอบให้แน่ใจว่าผู้ใช้ที่รับรองความถูกต้องมีสิทธิ์เข้าถึงทรัพยากร
3. ตรวจสอบประเภทกิจกรรมหรือรหัสกิจกรรมว่าถูกต้อง

422 เอนทิตีไม่สามารถประมวลผลได้

สาเหตุ: ข้อผิดพลาดในการตรวจสอบความถูกต้องในคำขอ

วิธีแก้ไข: ตรวจสอบการตอบสนองสำหรับรายละเอียด:

{
  "title": "ข้อผิดพลาดในการตรวจสอบความถูกต้อง",
  "message": "พารามิเตอร์ไม่ถูกต้อง: url ต้องเป็น HTTPS URL ที่ถูกต้อง"
}

ทางเลือกและการเปรียบเทียบ

Calendly มีเอกสารประกอบ API และขั้นตอน OAuth ที่ยอดเยี่ยมที่สุด Cal.com เป็นทางเลือกโอเพนซอร์สที่มีการรับรองความถูกต้องด้วย API key ที่ง่ายกว่า

กรณีการใช้งานจริง

การผสานรวม CRM การขาย บริษัท B2B SaaS ฝัง Calendly บนหน้าการกำหนดราคา เมื่อมีคนจองการสาธิต เว็บฮุกจะทริกเกอร์:

1. สร้างลีดใน Salesforce
2. ส่งการแจ้งเตือน Slack ไปยังทีมขาย
3. เพิ่มในลำดับการตลาดอัตโนมัติ
4. บันทึกกิจกรรมในแพลตฟอร์มความสำเร็จของลูกค้า

แพลตฟอร์มการปรึกษาหารือ แพลตฟอร์มบริการทางกฎหมายให้ลูกค้าจองการปรึกษาหารือกับทนายความ การผสานรวม API:

1. ซิงค์การจองกับระบบการกำหนดเวลาภายใน
2. สร้างลิงก์การประชุม Zoom
3. ส่งแบบสอบถามก่อน 24 ชั่วโมง
4. สร้างไฟล์เคสเมื่อการประชุมเสร็จสิ้น

การกำหนดเวลาการสัมภาษณ์ แพลตฟอร์มการสรรหาใช้ Calendly สำหรับการสัมภาษณ์ผู้สมัคร เว็บฮุก:

1. อัปเดต ATS ด้วยรายละเอียดการสัมภาษณ์
2. แจ้งผู้จัดการการจ้างงานทางอีเมล
3. ส่งคำเชิญเข้าร่วมปฏิทินไปยังผู้เข้าร่วมทั้งหมด
4. ติดตามผู้ที่ไม่มาตามนัดเพื่อติดตามผล

สรุป

สิ่งที่คุณได้เรียนรู้:

• Calendly ใช้ OAuth 2.0 สำหรับการรับรองความถูกต้อง API
• เข้าถึงประเภทกิจกรรมและกิจกรรมที่กำหนดเวลาไว้ผ่าน API
• เว็บฮุกให้การแจ้งเตือนการจองแบบเรียลไทม์
• ตรวจสอบลายเซ็นเว็บฮุกเสมอเพื่อความปลอดภัย
• ทดสอบด้วย Apidog ก่อนเชื่อมต่อกับปฏิทินจริง

ขั้นตอนต่อไปของคุณ:

1. สร้างแอปพลิเคชัน OAuth ใน Calendly
2. ใช้ขั้นตอน OAuth
3. ตั้งค่าการสมัครสมาชิกเว็บฮุก
4. ทดสอบด้วยเพย์โหลดจำลองใน Apidog
5. ปรับใช้ในการผลิต

ทดสอบเว็บฮุก Calendly ด้วย Apidog - ฟรี

คำถามที่พบบ่อย

ฉันจำเป็นต้องมีแผน Calendly แบบชำระเงินเพื่อใช้ API หรือไม่?ไม่ API มีให้ใช้งานในทุกแผนรวมถึงฟรี อย่างไรก็ตาม แผนฟรีมีคุณสมบัติที่จำกัด เว็บฮุกมีให้ใช้งานในทุกแผน

ความแตกต่างระหว่างเว็บฮุกระดับผู้ใช้และระดับองค์กรคืออะไร?เว็บฮุกระดับผู้ใช้จะจับภาพเหตุการณ์สำหรับผู้ใช้เพียงคนเดียวเท่านั้น เว็บฮุกระดับองค์กรจะจับภาพเหตุการณ์สำหรับสมาชิกในทีมทั้งหมด การผสานรวมส่วนใหญ่ใช้ขอบเขตองค์กร

ฉันจะรับคีย์การลงนามเว็บฮุกได้อย่างไร?เมื่อคุณสร้างเว็บฮุกผ่าน API การตอบสนองจะมี signing_key จัดเก็บสิ่งนี้อย่างปลอดภัย ใช้เพื่อตรวจสอบลายเซ็นเว็บฮุก

ฉันสามารถสร้างการจองผ่าน API ได้หรือไม่?ไม่ Calendly ไม่มีปลายทาง API สำหรับสร้างการจอง การจองจะต้องเกิดขึ้นผ่าน UI ของ Calendly หรือวิดเจ็ตที่ฝังไว้ API เป็นแบบอ่านอย่างเดียวสำหรับการจอง

ฉันจะจัดการการแปลงเขตเวลาได้อย่างไร?การประทับเวลาทั้งหมดใน API เป็น UTC (ISO 8601) แปลงเป็นเวลาท้องถิ่นในแอปพลิเคชันของคุณ เขตเวลาของผู้ใช้มีอยู่ในทรัพยากรผู้ใช้

ขีดจำกัดอัตราคืออะไร?Calendly ไม่ได้บันทึกขีดจำกัดอัตราต่อสาธารณะ ใช้รูปแบบคำขอที่เหมาะสม หากคุณถึงขีดจำกัด ให้ใช้ exponential backoff

ฉันสามารถรับการจองย้อนหลังได้หรือไม่?ได้ ใช้ min_start_time และ max_start_time เพื่อสอบถามกิจกรรมย้อนหลัง ไม่จำกัดว่าคุณสามารถสอบถามย้อนหลังไปได้ไกลแค่ไหน

ฉันจะทดสอบขั้นตอน OAuth ในเครื่องได้อย่างไร?ใช้บริการ tunneling เช่น ngrok เพื่อเปิดเผยเซิร์ฟเวอร์ในเครื่องของคุณ ตั้งค่า Redirect URI เป็น URL ของ ngrok ของคุณ ทำขั้นตอน OAuth ให้สมบูรณ์ในเบราว์เซอร์ จากนั้นตรวจสอบการเรียกกลับ