Skip to content

Calendar TCP API

Calendar events are planned manager actions with time boundaries: tasks, reminders, calls, meetings, follow-ups, deadlines, and system-created items.

Frontend calendar UI, including react-big-calendar, is a presentation layer over these backend records.

Access Control

All calendar methods require one of:

  • SESSION_MANAGER
  • SESSION_ADMIN
  • SESSION_DEALER
  • SESSION_CRM_MANAGER
  • SESSION_CRM_ADMIN

Manager permissions and scope are resolved from the cached staff manager record. The token is used only as the source of manager id and session type.

Calendar uses the existing note permission fields, but they are valid for both CRM and BackOffice managers. A manager must have either CRM access or BackOffice access, plus the required *_notes permission.

Permission fields:

  • see_notes is required for MngGetCalendarEvent and MngGetCalendarEventsByFilter
  • set_notes is required for MngAddCalendarEvent, MngUpdateCalendarEvent, MngArchiveCalendarEvent, and MngCompleteCalendarEvent
  • del_notes is required for MngDeleteCalendarEvent

Scope rules:

  • linked customer_id is checked through customer brand/desk scope for CRM and BackOffice managers
  • linked lead_id is checked through lead brand/desk scope for CRM and BackOffice managers
  • linked login is checked through the account's linked customer scope or BackOffice account group scope; when no customer is linked, CRM managers use account group brand and BackOffice managers use account group permissions plus brand
  • direct brand/desk events are checked against manager brand/desk scope; brand-only events are allowed inside the manager brand
  • events without linked entity and without brand are visible only to the owner or participant

Commands

  • MngAddCalendarEvent
  • MngUpdateCalendarEvent
  • MngDeleteCalendarEvent
  • MngArchiveCalendarEvent
  • MngCompleteCalendarEvent
  • MngGetCalendarEvent
  • MngGetCalendarEventsByFilter

Core Event Fields

Field Type Description
id int Calendar event id
brand string Brand namespace
desk string CRM desk code, for example DESK_RETENTION
owner_manager_id int Organizer or main assignee
created_by int Creator manager id
updated_by int Last updater manager id
type int 0 task, 1 reminder, 2 call, 3 meeting, 4 follow-up, 5 deadline, 6 system
status int 0 open, 1 done, 2 cancelled, 3 archived
priority int 0 low, 1 normal, 2 high, 3 urgent
title string Calendar title
ast_json object/array/string/null Visible AST message body
start_time, end_time time_t Unix timestamps
all_day int 0 no, 1 yes
remind_time time_t Absolute reminder time
remind_before_sec int Reminder offset before start
reminder_sent_time time_t Delivery marker
customer_id int Optional linked customer id
lead_id int Optional linked lead id
login int Optional linked trading account login
created_time, updated_time time_t Unix timestamps

ast_json is the rendered content. Google Meet links and entity mentions should be stored inside the AST. Scalar links (customer_id, lead_id, login) are kept for filtering and backend checks.

Defaults And Validation

On create:

  • if created_by = 0 or is omitted, backend uses the resolved staff manager id
  • if owner_manager_id = 0 or is omitted, backend sets owner_manager_id = created_by
  • owner is automatically added to participants as role = 0, status = 1

Time validation:

  • start_time must be greater than 0
  • end_time must be greater than or equal to start_time

To cancel an event, call MngUpdateCalendarEvent with status: 2. There is no separate cancel command.

Participants

Events can be assigned to multiple managers through participants.

Field Type Description
event_id int Calendar event id
manager_id int Participant manager id
role int 0 organizer, 1 required, 2 optional
status int 0 invited, 1 accepted, 2 declined, 3 tentative
created_time, updated_time time_t Unix timestamps

The event owner is automatically materialized as an organizer participant.

When creating or updating an event, participants can be sent in one of two formats:

{
  "participant_manager_ids": [10, 11, 12]
}

or:

{
  "participants": [
    {
      "manager_id": 10,
      "role": 0,
      "status": 1,
      "created_time": 1710000000,
      "updated_time": 1710000000
    }
  ]
}

If both participants and participant_manager_ids are sent, participants is used.

Desk Scope

Calendar list methods require deskFilter, a wildcard mask over desk, for example:

  • *
  • DESK_*
  • DESK_EU*,!DESK_EU_TEST

DESK_* does not match events with an empty desk. Use * to include all desks, including empty desk values.

See Desks TCP API.

Desk Meeting Flow

To create one meeting for several managers inside a desk:

  1. Frontend selects brand and desk.
  2. Frontend resolves or already knows manager ids for that desk.
  3. Frontend creates one calendar event.
  4. Frontend sends manager ids through participant_manager_ids or detailed participants.
  5. Google Meet link is inserted into ast_json as normal visible content.

Every participant receives the same shared event in their calendar when filtering by their manager_id.

Response Shape

Calendar methods that return an event return the full event object with participants. Examples in method pages may be shortened for readability.

Frontend Mapping

For react-big-calendar:

  • title -> title
  • start_time -> start
  • end_time -> end
  • all_day -> allDay
  • full event object -> resource