Skip to content

Support bot and call booking

For the Velora team: the Telegram support bot and the iCloud calendar for calls.

15 min

This guide is for the team running Velora, not for agencies. It connects two things: the Telegram bot that answers questions from the Support page, and the Book a call page linked to the iCloud calendar.

Before you start

  • Access to the app's environment variables (Railway or Vercel).
  • Telegram on your phone.
  • The Apple account that holds the "Réunion" calendar.

The Telegram bot

  1. Create the bot. In Telegram, open @BotFather, send /newbot, then pick a username ending in bot, for example VeloraSupportBot. Copy the token.
  2. Create the team group. A Telegram group with you and the assistant, then add the bot as a member. The bot only reads replies to its own messages: no need to make it admin.
  3. Get the group id. Send a message in the group, then open https://api.telegram.org/bot<TOKEN>/getUpdates in your browser before step 5. The id starts with -100.
  4. Fill in the variables. SUPPORT_TELEGRAM_BOT_TOKEN (the token), SUPPORT_TELEGRAM_WEBHOOK_SECRET (the output of openssl rand -hex 32), SUPPORT_TEAM_CHAT_ID (the group id) and NEXT_PUBLIC_SUPPORT_TELEGRAM_URL (for example https://t.me/VeloraSupportBot). ANTHROPIC_API_KEY is optional: with it, Claude answers from the guides; without it, the bot searches by keywords.
  5. Connect the webhook. Once the app is redeployed, run the script from apps/web: ../../packages/db/node_modules/.bin/tsx scripts/support-bot-setup.ts. It sets the webhook with its secret and the command menu in French, English and Spanish. --check shows the status without changing anything.
  6. Test. Send /start to the bot, then tap "Talk to a human". The message lands in the group: answer it with Telegram's Reply, and the person gets your answer. Reply /fin to hand the conversation back to the bot.

The iCloud calendar

  1. Create an app-specific password. On appleid.apple.com, open Sign-In and Security, then App-Specific Passwords, and create one named "Velora". It is not your Apple ID password.
  2. Fill in the variables. ICLOUD_CALDAV_USER (the Apple ID e-mail), ICLOUD_CALDAV_APP_PASSWORD (the app-specific password) and ICLOUD_CALDAV_CALENDAR (Réunion, the exact calendar name).
  3. Choose what blocks slots. By default, only events of the "Réunion" calendar take a slot. Set ICLOUD_CALDAV_BUSY_CALENDARS=* to count all your calendars, or a comma-separated list of names.
  4. Add your video link if you have one. BOOKING_MEETING_URL (a fixed https link) goes in the e-mail and the event.
  5. Test. Book a slot on /en/reserver-un-appel. The call shows up in "Réunion", the confirmation e-mail arrives with the invite, and the Telegram group gets the notice. The cancel link of the e-mail frees the slot and removes the event.

If it doesn't work

  • The bot doesn't answer → run the script with --check: it shows the webhook's last error. Check the secret is the same in the app and in the script.
  • The assistant's answer doesn't arrive → she must answer the bot's message with Reply, not write a new message.
  • No slot on the page → the iCloud calendar doesn't answer or the name doesn't match. Without the iCloud variables, the page works with the existing bookings only.
  • The app-specific password leaked → revoke it on appleid.apple.com and create another one.

Official links