ARKH Developer Portal

Vibes (Haptics)

Vibes allow your app to send haptic feedback directly to a user's ARKH Ring. This creates a tactile communication channel - perfect for notifications, alerts, confirmations, or any interaction that benefits from physical feedback.

Patterns

ARKH provides two base haptic patterns. You can send a sequence of up to 3 patterns, each with an optional delay before the next.

Pattern

Description

tap

Quick, light tap. Subtle and unobtrusive.

pulse

Longer, fuller vibration. More noticeable.

List Available Patterns

curl -X GET "https://developer.arkh.com/api/vibes/patterns" \
  -H "Authorization: Bearer arkh_your_api_key_here"

Response

{
  "patterns": ["tap", "pulse"],
  "max_sequence_length": 3
}

Triggering Vibes

Use the /vibes/trigger endpoint to send a haptic notification to a user's ring. Pass a sequence of up to 3 patterns, each with an optional delay_ms before the next pattern plays. Use @me as the user_app_id to target yourself for testing.

Trigger a Vibe

curl -X POST "https://developer.arkh.com/api/vibes/trigger" \
  -H "Authorization: Bearer arkh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_app_id": "@me",
    "app_id": "app_01234567",
    "sequence": [
      { "type": "tap", "delay_ms": 100 },
      { "type": "tap", "delay_ms": 100 },
      { "type": "pulse" }
    ],
    "message": "Order shipped!",
    "show_ring_ui_notif": true
  }'

Response

{
  "success": true,
  "event_id": "731c520e-82a7-457a-ae18-7b5a866ba95a",
  "delivery": {
    "method": "realtime",
    "status": "delivered",
    "latency_ms": 142,
    "app_state": "active"
  }
}

Permission Denied Response

{
  "error": {
    "code": "permission_disabled",
    "message": "User has disabled vibes for this app."
  }
}

Good to Know

Rate Limiting: Max 30 vibes per user per minute (sliding window). This protects users' ring battery from excessive vibrations. Each API call counts as one vibe regardless of sequence length. Exceeding this returns a 429 error. All API calls (including vibes) are also subject to the global API key limit of 100 requests per 60 seconds.

Privacy Controls: Vibe permissions are enabled by default. Users can disable vibes by tapping your app in the widget manager—if disabled, trigger requests return a permission_disabled error.

Ring UI Notifications

By default, vibes are haptic-only—the user feels the vibration but sees nothing on screen. Set show_ring_ui_notif: true to display a visual notification alongside the haptic feedback.

When enabled, your app name and message appear on the user's Ring UI:

Dynamic Island — Expands to show your app name and message when the phone is unlocked
Lock Screen — Appears as a Live Activity notification
In-App Toast — Shows as an overlay when the companion app is open

Ring UI Notification Details

Auto-dismiss: Notifications automatically clear after 5 seconds.

Hold to dismiss: Users can hold on the notification to dismiss it early.

Message limit: 80 characters max. API rejects longer messages.

Requires message: show_ring_ui_notif only works when message is also provided.

Ring UI notifications are ideal for confirmations the user should see—"Order shipped!", "Payment received", "Download complete". For background updates that don't need visual confirmation, use haptic-only vibes.

Common Use Cases

Single tap — Subtle confirmations, background updates
Double tap — Action completed, message received
Triple tap — Important notification, requires attention
Single pulse — Timer finished, reminder
Double pulse — Urgent alert, incoming call
tap + pulse — Critical alert, emergency

See the /vibes API for full API reference.