calendar.event.add

What calendar.event.add does

Creates events in user, group, or company calendars. The scheduling half of booking integrations: property viewings, clinic appointments, demo calls — created from external systems onto the right person's calendar.

Business use cases

• Booking systems placing viewings/appointments on agent calendars
• Clinic scheduling synced to doctor calendars
• Demo-call scheduling from website booking widgets
• Resource booking (rooms, vehicles) via calendar.resource.*

Typical fields and parameters

• type + ownerId — 'user' + user ID for personal calendars; 'group' for workgroup calendars
• section — Calendar section ID — list with calendar.section.get; events land invisibly if the section is wrong
• name / description — What appears on the calendar
• from / to — Start/end datetimes — timezone discipline is everything here
• attendees + host — Participant user IDs for meeting-style events
• remind — Reminder rules (e.g. 15 minutes before)

Example workflow

1. Client books a Friday 15:00 viewing in the booking widget
2. Availability checked against calendar.event.get for the agent's window
3. calendar.event.add creates the event on the agent's calendar with a 1-hour reminder
4. crm.activity.add mirrors it as a meeting on the lead; WhatsApp confirmation goes to the client

Example request

POST .../calendar.event.add.json

{
  "type": "user",
  "ownerId": 7,
  "section": 21,
  "name": "Viewing — Marina Vista 2104 — Ahmed",
  "description": "Lead #20517. Meet at tower lobby.",
  "from": "2026-07-10T15:00:00+04:00",
  "to": "2026-07-10T15:45:00+04:00",
  "remind": [{ "type": "min", "count": 60 }]
}

Example response

{ "result": 5521, "time": { ... } }
// "result" is the new event ID.

Field mapping notes

• Calendar events do not automatically appear on CRM records — mirror with a CRM activity/todo if agents work from the record
• Store the event ID against your booking so reschedules and cancellations can target it (calendar.event.update / delete)
• Timezones: send explicit offsets and test with a portal whose timezone differs from your server's — this is the #1 bug source in booking integrations

Security notes

• Calendar contents reveal client names and movements — scope the integration account's calendar access to the users it schedules for

Common errors

• Event created but not visible — Wrong section for that owner — list sections per user, don't reuse IDs across users
• Times shifted by hours — Timezone offset mismatch between your system, the portal, and the user profile
• Double bookings — No availability check, or check-then-create race — serialize per-agent in the queue

Production implementation tips

• Always check availability and create within one serialized worker per agent to prevent races
• Reminders are your no-show insurance — set both calendar remind and a WhatsApp reminder cadence

Webhook or OAuth app?

Booking flows touch many users' calendars — an OAuth app with calendar scope is cleaner than a super-user webhook.

Full decision guide: webhook vs OAuth app in Bitrix24.

When to use a queue worker

Serialize by agent for race-free booking; everything else follows the standard queue pattern.

How Tech Titan can help

Tech Titan builds production Bitrix24 integrations around calendar.event.add and its siblings — with authentication, field mapping, queue workers, retry logic, duplicate handling, and structured logs as standard. If this method is on your critical path, bring the requirement to a free audit call and leave with an architecture sketch.