Meetings API — Teams Meeting Creation via Graph API

The /api/meetings route creates Microsoft Teams calendar events through the Microsoft Graph API and returns a Teams join URL that can be sent directly to attendees or surfaced within the virtual office. Events are created on the organiser’s calendar with isOnlineMeeting: true, which causes Teams to generate a join link automatically. In development mode — when Azure AD credentials are not configured — the route returns a mock meeting object with a generated dev-{timestamp} ID so the UI booking flow can be exercised without a live Microsoft 365 tenant.

POST /api/meetings

Request

Property	Value
Method	`POST`
Path	`/api/meetings`
Content-Type	`application/json`

Body Parameters

titulo

string

required

The meeting subject line as it will appear in the Teams calendar event.

fecha

string

required

ISO 8601 datetime string for the meeting start time — e.g. "2025-09-15T14:00:00-05:00". The route validates that this date is in the future before proceeding. The calendar event timezone is set to America/Bogota.

duracionMinutos

number

required

Meeting duration in minutes. The end time is computed as start + duracionMinutos * 60000 milliseconds.

sala

string

required

The virtual office room context where the meeting was requested — e.g. "ejecutiva", "compliance". Used to set the event location (Oficina Virtual GCS - {sala}) and is embedded in the HTML event body.

asistentes

array

required

Array of attendee objects. At least one attendee is required. All attendees are added with type: "required".

Show asistentes[] properties

asistentes[].nombre

string

required

Display name of the attendee, used in the Teams invitation.

asistentes[].email

string

required

Email address of the attendee. Receives the Teams calendar invitation.

descripcion

string

Optional meeting description or agenda text. Rendered as HTML inside the event body. Defaults to "Reunión agendada desde la Oficina Virtual de GCS Consultores Empresariales." when not provided.

organizadorEmail

string

Overrides the DEFAULT_ORGANIZER_EMAIL environment variable for this specific request. The meeting is created under this user’s calendar and they receive organiser-level permissions.

Response

Success (Teams)
Development mode
Error

{
  "success": true,
  "message": "Reunión creada exitosamente",
  "meeting": {
    "id": "<teams-event-id>",
    "joinUrl": "https://teams.microsoft.com/l/meetup-join/...",
    "titulo": "Consultoría SARLAFT",
    "fecha": "2025-09-15T14:00:00-05:00",
    "duracion": 60,
    "sala": "compliance"
  }
}

{
  "success": true,
  "message": "Solicitud de reunión registrada (modo desarrollo)",
  "meeting": {
    "id": "dev-1726415200000",
    "joinUrl": null,
    "titulo": "Consultoría SARLAFT",
    "fecha": "2025-09-15T14:00:00-05:00",
    "duracion": 60,
    "sala": "compliance"
  },
  "note": "Configure las variables de entorno de Microsoft 365 para crear reuniones reales de Teams"
}

{ "error": "La fecha de la reunión debe ser futura" }

HTTP status will be 400 for validation errors or 500 for Graph API / server errors.

Response Fields

success

boolean

true on all non-error responses, including development-mode fallbacks.

meeting.id

string

The Teams event ID returned by Microsoft Graph — or "dev-{timestamp}" in development mode.

meeting.joinUrl

string | null

The Teams meeting join URL sourced from event.onlineMeeting.joinUrl. null in development mode when no Graph API call is made.

meeting.titulo

string

Echo of the submitted titulo field.

meeting.fecha

string

Echo of the submitted fecha ISO 8601 string.

meeting.duracion

number

Echo of the submitted duracionMinutos value.

meeting.sala

string

Echo of the submitted sala room identifier.

GET /api/meetings

The GET handler lets Sally check whether a user has an upcoming meeting — used to trigger Sally’s contextualised greeting when a user returns to the virtual office near a scheduled session.

GET /api/meetings?email=user@example.com

Query Parameter	Type	Description
`email`	string	The user’s email to look up in the calendar

Without email: returns usage documentation.

{
  "message": "Endpoint para verificar reuniones próximas",
  "usage": "GET /api/meetings?email=user@example.com"
}

With email: returns the upcoming-meeting status. Until Microsoft Graph is fully configured, the route always returns:

{
  "hasUpcomingMeeting": false,
  "nextMeeting": null,
  "note": "Configure Microsoft Graph API para obtener reuniones reales"
}

In a future iteration, this endpoint will query the organiser’s calendar via GET https://graph.microsoft.com/v1.0/users/{email}/calendarView with a time window around now to surface real upcoming meetings to Sally.

Microsoft Teams Integration

Creating a Teams meeting involves two Graph API calls:

Obtain OAuth2 client_credentials token

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded

client_id=<AZURE_AD_CLIENT_ID>
&client_secret=<AZURE_AD_CLIENT_SECRET>
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials

If credentials are missing the route skips to development-mode fallback.

Create the calendar event

POST https://graph.microsoft.com/v1.0/users/{organizerEmail}/events

Authorization: Bearer <token>
Content-Type: application/json

The event payload includes:

{
  "subject": "<titulo>",
  "body": { "contentType": "HTML", "content": "..." },
  "start": { "dateTime": "<ISO 8601>", "timeZone": "America/Bogota" },
  "end":   { "dateTime": "<ISO 8601>", "timeZone": "America/Bogota" },
  "location": { "displayName": "Oficina Virtual GCS - <sala>" },
  "attendees": [
    {
      "emailAddress": { "address": "<email>", "name": "<nombre>" },
      "type": "required"
    }
  ],
  "isOnlineMeeting": true,
  "onlineMeetingProvider": "teamsForBusiness"
}

Extract the join URL

Microsoft Graph returns the created event object. The route reads event.onlineMeeting.joinUrl and returns it in the response body. If the field is missing (e.g. the tenant does not have Teams licences), joinUrl is returned as an empty string.

Example Request

const response = await fetch('/api/meetings', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    titulo: 'Diagnóstico inicial SARLAFT',
    descripcion: 'Revisión de nivel de madurez y plan de acción.',
    fecha: '2025-09-15T14:00:00-05:00',
    duracionMinutos: 60,
    sala: 'compliance',
    asistentes: [
      { nombre: 'Carlos Pérez', email: 'carlos.perez@empresa.com.co' }
    ],
    organizadorEmail: 'consultor@gcsconsultores.com'
  })
})

const data = await response.json()
console.log(data.meeting.joinUrl) // Teams join link

Validation

The route performs server-side validation before any external call is attempted:

Required fields: titulo, fecha, duracionMinutos, sala — returns 400 if any are missing.
Attendees: asistentes array must contain at least one entry — returns 400 otherwise.
Future date: new Date(fecha) > new Date() must be true — returns 400 if the meeting is in the past or present.

Error Responses

Status	Description
`400`	Missing required fields (`titulo`, `fecha`, `duracionMinutos`, `sala`)
`400`	No attendees provided (`asistentes` array is empty or absent)
`400`	Meeting date is not in the future
`500`	Microsoft Graph API error or unexpected server error

This route requires AZURE_AD_CLIENT_ID, AZURE_AD_CLIENT_SECRET, AZURE_AD_TENANT_ID, and DEFAULT_ORGANIZER_EMAIL to create real Teams meetings. Without these variables, all requests succeed in development mode but no calendar event or join URL is generated.

The organiser’s Azure AD account needs the Calendars.ReadWrite application permission granted (not delegated) in your Azure AD app registration. Application permissions allow the route to create events on behalf of any user in the tenant without interactive sign-in.

API Reference

Integrations

Configuration

Meetings API — Teams Meeting Creation via Graph API

POST /api/meetings

Request

Body Parameters

Response

Response Fields

GET /api/meetings

Microsoft Teams Integration

Example Request

Validation

Error Responses

Build docs developers (and LLMs) love

API Reference

Integrations

Configuration

Documentation Index

​POST /api/meetings

​Request

​Body Parameters

​Response

​Response Fields

​GET /api/meetings

​Microsoft Teams Integration

​Example Request

​Validation

​Error Responses

Build docs developers (and LLMs) love

POST /api/meetings

Request

Body Parameters

Response

Response Fields

GET /api/meetings

Microsoft Teams Integration

Example Request

Validation

Error Responses