Internal reference — not the public API

This documents NearSync's internal action-dispatch surface, used by the apps themselves and by tenant automations. It is not the public API and carries no stability guarantee — actions may change or be removed without notice. For the supported, versioned public API see API Reference.

Communications Endpoints

Endpoints for sending emails, WhatsApp messages, managing voice calls, and handling chat conversations. Covers Gmail integration, Meta WhatsApp Business API, and Twilio voice.

All endpoints use POST to the hyper-worker base URL with the type field specifying the action.

POST https://<project>.supabase.co/functions/v1/hyper-worker

Email

send-email

Authenticated - Requires JWT.

Send an email via Gmail with optional open tracking. The email is sent from the authenticated user's connected Gmail account.

Rate limit: 10 requests per 60 seconds

Request

{
  "type": "send-email",
  "to": "recipient@example.com",
  "cc": "cc@example.com",
  "bcc": "bcc@example.com",
  "subject": "Meeting Notes",
  "body": "<p>HTML content</p>",
  "userEmail": "sender@example.com",
  "trackingId": "<uuid>"
}

Field	Type	Required	Description
`to`	string	Yes	Recipient email address
`cc`	string	No	CC recipient
`bcc`	string	No	BCC recipient
`subject`	string	Yes	Email subject line
`body`	string	Yes	Email body (HTML supported)
`userEmail`	string	Yes	Sender's Gmail address (must have an active Google integration)
`trackingId`	string	No	UUID for open tracking. If provided, a 1x1 tracking pixel is appended to the email body

Process

If trackingId is provided, appends a tracking pixel URL to the email body
Logs the message to the email_messages table with tracking metadata
Constructs an RFC 822 formatted message, base64url-encodes it
Sends via the Gmail API

Response

{
  "success": true
}

fetch-inbox

Authenticated - Requires JWT.

Fetch Gmail inbox messages for a connected user. Returns message metadata (not full body content).

{
  "type": "fetch-inbox",
  "userEmail": "user@example.com",
  "labelId": "INBOX"
}

Field	Type	Required	Description
`userEmail`	string	Yes	Gmail address to fetch from
`labelId`	string	No	Gmail label filter (default: `INBOX`)

Response:

{
  "emails": [
    {
      "id": "<message-id>",
      "from": "sender@example.com",
      "subject": "Project Update",
      "preview": "Here's the status...",
      "date": "2026-03-21T10:00:00Z",
      "unread": true
    }
  ]
}

Returns up to 10 messages per request.

fetch-email-detail

Authenticated - Requires JWT.

Get the full content of a specific email message, with the body decoded from base64.

{
  "type": "fetch-email-detail",
  "id": "<message-id>",
  "userEmail": "user@example.com"
}

Response:

{
  "body": "<p>Email content...</p>",
  "mimeType": "text/html"
}

mark-email-read

Authenticated - Requires JWT.

Mark a Gmail message as read by removing the UNREAD label.

{
  "type": "mark-email-read",
  "id": "<message-id>",
  "userEmail": "user@example.com"
}

Response:

{
  "success": true
}

send-whatsapp

Authenticated - Requires JWT.

Send a WhatsApp message via the Meta Business API. Supports both plain text messages and pre-approved templates.

Rate limit: 20 requests per 60 seconds

Request

{
  "type": "send-whatsapp",
  "to": "+1234567890",
  "message": "Hello, your booking is confirmed",
  "templateName": "meeting_confirmed_v1",
  "language": "en_US",
  "templateVars": ["John", "March 25"]
}

Field	Type	Required	Description
`to`	string	Yes	Recipient phone number in E.164 format
`message`	string	Conditional	Plain text message body. Required if `templateName` is not provided
`templateName`	string	No	Pre-approved WhatsApp template name. If provided, `message` is ignored
`language`	string	No	Template language code (default: `en_US`)
`templateVars`	string[]	No	Variable values for template placeholders, in order

Process

Retrieves WhatsApp Business Account credentials from organization settings
If templateName is provided, sends a template message with variable substitution
Otherwise, sends a plain text message
Calls the Meta Graph API messaging endpoint

Response

{
  "success": true,
  "messages": [
    {
      "id": "wamid.xxx",
      "status": "accepted"
    }
  ]
}

Template messages

WhatsApp requires pre-approved templates for initiating conversations outside the 24-hour customer service window. Plain text messages can only be sent in reply to a customer-initiated conversation within that window.

Voice

get-voice-token

Authenticated - Requires JWT.

Generate a Twilio access token for client-side voice calling. The token includes a VoiceGrant for the Twilio Client SDK.

{
  "type": "get-voice-token",
  "identity": "user-identity"
}

Field	Type	Required	Description
`identity`	string	Yes	Unique identity for the Twilio client (typically the user's ID or email)

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Use this token to initialize the Twilio Client SDK in the browser for making and receiving calls.

Chat Management

fetch-admin-chats

Authenticated - Requires JWT.

Fetch all chat conversations with unread counts. Used to populate the admin chat inbox.

{
  "type": "fetch-admin-chats",
  "filter": "whatsapp"
}

Field	Type	Required	Description
`filter`	string	No	Filter by conversation type (e.g., `whatsapp`, `web_chat`)

Response:

{
  "conversations": [
    {
      "project_id": "<uuid>",
      "business_name": "Acme Corp",
      "client_name": "John Smith",
      "assigned_name": "Jane Doe",
      "last_message_at": "2026-03-21T10:00:00Z",
      "last_message_preview": "Thanks for the update...",
      "unread_count": 3,
      "project_type": "whatsapp",
      "session_status": "open",
      "assigned_to": "<uuid>"
    }
  ]
}

fetch-chat-history

Authenticated - Requires JWT.

Get the full message history for a conversation, ordered chronologically.

{
  "type": "fetch-chat-history",
  "projectId": "<uuid>"
}

Response:

{
  "history": [
    {
      "id": "<uuid>",
      "created_at": "2026-03-21T10:00:00Z",
      "comment_text": "Hello, I need help",
      "author": "John Smith",
      "author_id": "<uuid>",
      "comment_type": "user",
      "attachments": []
    }
  ]
}

update-chat-session

Authenticated - Requires JWT.

Close or claim a chat session.

{
  "type": "update-chat-session",
  "projectId": "<uuid>",
  "action": "close",
  "userId": "<uuid>"
}

Field	Type	Required	Description
`projectId`	string	Yes	Deal/project ID
`action`	string	Yes	`close` to end the session, `claim` to assign it to yourself
`userId`	string	Yes	Your user ID (used for `claim` action)

Response:

{
  "success": true
}

link-whatsapp-contact

Authenticated - Requires JWT.

Link a WhatsApp conversation to an existing contact or deal. Merges message history from the source to the target.

{
  "type": "link-whatsapp-contact",
  "projectId": "<uuid>",
  "name": "Contact Name",
  "email": "contact@example.com",
  "targetProjectId": "<uuid>"
}

Field	Type	Required	Description
`projectId`	string	Yes	Source project (the unlinked WhatsApp conversation)
`name`	string	No	Contact name
`email`	string	No	Contact email
`targetProjectId`	string	Yes	Destination project to merge into

Response:

{
  "success": true,
  "merged": true
}

log-web-chat

Authenticated - Requires JWT.

Log a web chat message. If this is the first message for the given session, a new deal is automatically created with round-robin admin assignment.

{
  "type": "log-web-chat",
  "sessionId": "<session-id>",
  "message": "Hello, I need help",
  "role": "user"
}

Field	Type	Required	Description
`sessionId`	string	Yes	Chat session identifier
`message`	string	Yes	Message text
`role`	string	Yes	Message author role: `user` or `agent`

Response:

{
  "success": true,
  "projectId": "<uuid>"
}

Google Calendar & Meet

fetch-calendar

Authenticated - Requires JWT.

Get upcoming calendar events for the next 30 days from a connected Google Calendar.

{
  "type": "fetch-calendar",
  "userEmail": "user@example.com"
}

Response:

{
  "events": [
    {
      "id": "<event-id>",
      "summary": "Team Meeting",
      "start": "2026-03-22T10:00:00Z",
      "end": "2026-03-22T11:00:00Z",
      "location": "Conference Room A",
      "attendees": [{ "email": "attendee@example.com" }]
    }
  ]
}

Returns up to 10 events.

create-meet-event

Authenticated - Requires JWT.

Create a Google Calendar event with an auto-generated Google Meet link.

{
  "type": "create-meet-event",
  "roomName": "Sprint Planning",
  "userEmail": "user@example.com"
}

Field	Type	Required	Description
`roomName`	string	Yes	Event title / meeting room name
`userEmail`	string	Yes	Calendar owner's email

Response:

{
  "success": true,
  "meetLink": "https://meet.google.com/abc-defg-hij",
  "eventId": "<event-id>"
}

Webhooks - Incoming WhatsApp and Twilio webhook handlers
Booking Endpoints - Booking confirmations send WhatsApp templates

Email​

send-email​

Request​

Process​

Response​

fetch-inbox​

fetch-email-detail​

mark-email-read​

WhatsApp​

send-whatsapp​

Request​

Process​

Response​

Voice​

get-voice-token​

Chat Management​

fetch-admin-chats​

fetch-chat-history​

update-chat-session​

link-whatsapp-contact​

log-web-chat​

Google Calendar & Meet​

fetch-calendar​

create-meet-event​

Related​

Email

send-email

Request

Process

Response

fetch-inbox

fetch-email-detail

mark-email-read

WhatsApp

send-whatsapp

Request

Process

Response

Voice

get-voice-token

Chat Management

fetch-admin-chats

fetch-chat-history

update-chat-session

link-whatsapp-contact

log-web-chat

Google Calendar & Meet

fetch-calendar

create-meet-event

Related