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 vk_live_7f8a92bc3e01d4a98402f...

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 1:1 messages, group announcements, and free carrier SMS.
`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`	Manage shul, yeshiva, and neighborhood organizations.
`catalog:read` / `catalog:write`	Manage business storefront items, products, and gemach catalogs.
`directory:read`	Look up verified community member listings.

Rate Limits & Business Quotas

Standard personal-automation keys are budgeted for 60 requests per minute per user. For verified businesses, shul broadcast bots, and storefront integrations, keys flagged with is_business = true automatically unlock an expanded limit of 300 requests per minute.

Messages & Free SMS Endpoint

POST /v1/messages

Send an instant message to another Vutsapp account, or pass is_sms_fallback: true to dispatch as a free carrier SMS to any standard or kosher flip phone.

curl -X POST https://api.vutsapp.com/v1/messages \
  -H "Authorization: Bearer vk_live_7f8a92bc3e01d4a" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+17185550199",
    "content": "Shacharis minyan is moved to 7:00 AM in the Bais Medrash.",
    "is_sms_fallback": true
  }'

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 vk_live_7f8a92bc3e01d4a" \
  -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 vk_live_7f8a92bc3e01d4a" \
  -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_8f7b2c9a1e0d4..." \
  -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.