Vutsapp Developer REST API v1

Overview & RLS Safety

The Vutsapp REST API v1 enables shuls, schools, community organizations, and individual developers to automate messaging, publish status updates, and integrate communal workflows.

DATABASE-LEVEL ENFORCEMENT

Unlike conventional platforms that grant APIs unfettered master keys, every authenticated Vutsapp API call evaluates PostgreSQL Row-Level Security (RLS) as the key's owner. A row or chat that RLS prohibits you from reading in-app is equally inaccessible over the API. Scopes provide an explicit capability boundary on top of database permissions.

Authentication

Every request must include an HTTP Authorization header using a Bearer token:

Authorization: Bearer $VUTSAPP_API_KEY

How to Mint an API Key

Open the Vutsapp client (iOS, Android, or Web).
Go to Settings → Developer → API keys.
Click Mint New Key. Select your required scopes and optional rate limit.
Copy your vk_... token. The secret is hashed with SHA-256 and never stored in plaintext.

Permission Scopes

API keys enforce granular, capability-gated scopes:

Scope	Grants & Description
`message:send`	Send text messages to chats and channels allowed by database permissions.
`status:read` / `status:write`	Read and post ephemeral kosher status updates with gender visibility controls.
`chat:read` / `chat:write`	Fetch chat threads, mark receipts, and manage conversation history.
`community:read` / `community:write`	Join or leave communities where database permissions allow it.
`catalog:read` / `catalog:write`	Manage business storefront items, products, and gemach catalogs.
`directory:read`	Look up verified community member listings.

Rate Limits & Business Quotas

The default is 60 requests per minute. A key's configured limit is capped at 1000 requests per minute; no business tier is granted automatically.

Messages Endpoint

POST /v1/messages

Send a text message to an existing chat you are allowed to use. The public API does not accept an SMS fallback flag.

curl -X POST https://api.vutsapp.com/v1/messages \
  -H "Authorization: Bearer $VUTSAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "00000000-0000-0000-0000-000000000000",
    "body": "Shacharis minyan is moved to 7:00 AM in the Bais Medrash."
  }'

Kosher Status Updates (Stories)

POST /v1/status

Publish an ephemeral 24-hour update with granular halachic visibility (all, same_gender, or custom).

curl -X POST https://api.vutsapp.com/v1/status \
  -H "Authorization: Bearer $VUTSAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Mazel Tov to the Miller family on the birth of a daughter!",
    "visibility": "same_gender",
    "expires_in_hours": 24
  }'

Communities & Channels API

Manage and automate shul, yeshiva, and neighborhood community channels. Post announcements, stream notifications, and synchronize membership rosters programmatically.

Available Endpoints

Method & Route	Required Scope	Description
GET `/v1/communities`	`community:read`	List all communities the authenticated account belongs to.
GET `/v1/communities/{id}/channels`	`community:read`	List all channels inside a community (filtered by halachic permissions).
GET `/v1/channels/{id}/messages`	`channel:read`	Fetch paginated message feed for a channel. Accepts `?limit=` and `?before=`.
POST `/v1/channels/{id}/messages`	`channel:write`	Publish an announcement to the channel. Caller must have posting rights.
POST `/v1/channels/{id}/members`	`channel:write`	Join a channel (respects channel approval and gender restrictions).
DELETE `/v1/channels/{id}/members`	`channel:write`	Leave a channel.

Post Announcement to Channel Example

curl -X POST https://api.vutsapp.com/v1/channels/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages \
  -H "Authorization: Bearer $VUTSAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Reminder: Daf Yomi shiur starts in the Main Bais Medrash at 8:30 PM."
  }'

Webhook Gateway

The Vutsapp Webhook Gateway connects external services (Zapier, Make.com, shul management databases, or custom scripts) directly to Vutsapp channels without requiring continuous polling.

1. Incoming Webhooks (Push Alerts into Channels)

Create an incoming webhook in Channel Settings → Integrations → Webhooks. You will receive a unique Webhook ID and secret.

POST https://api.vutsapp.com/webhook-gateway?id={WEBHOOK_UUID}

curl -X POST "https://api.vutsapp.com/webhook-gateway?id=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "x-webhook-secret: whsec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Emergency Tehillim alert: Please daven for Refoel ben Sarah.",
    "username": "Community Alert Bot"
  }'

2. Outgoing Webhooks (Event Dispatching)

Configure outgoing webhooks to notify your server whenever events occur in a community or channel (e.g. message.created, member.joined). Every dispatch includes a cryptographic signature in the X-Vutsapp-Signature header verified against your webhook secret.