docs(broadcasts,surveys): Complete API reference documentation
- OpenAPI-style reference for all admin and public endpoints - Request/response examples for broadcasts and surveys - Types reference, error codes, rate limits, webhooks
This commit is contained in:
saravanakumardb1
parent
c4c84ddf16
commit
3842f65c81
750
docs/BROADCAST_SURVEY_API_REFERENCE.md
Normal file
750
docs/BROADCAST_SURVEY_API_REFERENCE.md
Normal file
@ -0,0 +1,750 @@
|
|||||||
|
# Broadcast & Survey API Reference
|
||||||
|
|
||||||
|
> **Base URL**: `https://api.bytelyst.io/v1`
|
||||||
|
> **Authentication**: Bearer token (JWT) required for all endpoints except public ones
|
||||||
|
> **Product ID**: All requests must include `X-Product-ID` header
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
```http
|
||||||
|
Authorization: Bearer <jwt_token>
|
||||||
|
X-Product-ID: <product_id>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Broadcasts
|
||||||
|
|
||||||
|
### Admin Endpoints
|
||||||
|
|
||||||
|
#### List Broadcasts
|
||||||
|
```http
|
||||||
|
GET /admin/broadcasts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Query Parameters:**
|
||||||
|
| Parameter | Type | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| `status` | string | Filter by status: `draft`, `scheduled`, `sending`, `paused`, `completed` |
|
||||||
|
| `channel` | string | Filter by channel: `push`, `in_app`, `email`, `sms` |
|
||||||
|
| `limit` | integer | Max items (default: 20, max: 100) |
|
||||||
|
| `offset` | integer | Pagination offset |
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"broadcasts": [
|
||||||
|
{
|
||||||
|
"id": "bc_123456789",
|
||||||
|
"productId": "lysnrai",
|
||||||
|
"title": "New Feature Announcement",
|
||||||
|
"body": "Check out our latest update!",
|
||||||
|
"channel": "push",
|
||||||
|
"priority": "high",
|
||||||
|
"status": "completed",
|
||||||
|
"target": {
|
||||||
|
"platforms": ["ios", "android"],
|
||||||
|
"userSegments": ["pro"],
|
||||||
|
"percentageRollout": 100
|
||||||
|
},
|
||||||
|
"metrics": {
|
||||||
|
"targetedCount": 1500,
|
||||||
|
"sentCount": 1500,
|
||||||
|
"deliveredCount": 1420,
|
||||||
|
"openedCount": 890,
|
||||||
|
"clickedCount": 340,
|
||||||
|
"dismissedCount": 45
|
||||||
|
},
|
||||||
|
"createdAt": "2024-01-15T10:30:00Z",
|
||||||
|
"updatedAt": "2024-01-15T10:35:00Z"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 47,
|
||||||
|
"limit": 20,
|
||||||
|
"offset": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Get Broadcast
|
||||||
|
```http
|
||||||
|
GET /admin/broadcasts/:id
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:** Single broadcast object (same as list item)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Create Broadcast
|
||||||
|
```http
|
||||||
|
POST /admin/broadcasts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"title": "New Feature Announcement",
|
||||||
|
"body": "Check out our latest update with voice commands!",
|
||||||
|
"channel": "push",
|
||||||
|
"priority": "high",
|
||||||
|
"style": "banner",
|
||||||
|
"ctaText": "Try it now",
|
||||||
|
"ctaUrl": "https://app.bytelyst.io/voice",
|
||||||
|
"imageUrl": "https://cdn.bytelyst.io/banner/voice.jpg",
|
||||||
|
"target": {
|
||||||
|
"platforms": ["ios", "android"],
|
||||||
|
"userSegments": ["pro"],
|
||||||
|
"appVersionMin": "2.0.0",
|
||||||
|
"appVersionMax": null,
|
||||||
|
"countryCodes": ["US", "CA"],
|
||||||
|
"percentageRollout": 100,
|
||||||
|
"specificUserIds": null
|
||||||
|
},
|
||||||
|
"scheduledAt": "2024-01-20T09:00:00Z",
|
||||||
|
"expiresAt": "2024-02-20T09:00:00Z",
|
||||||
|
"deepLink": {
|
||||||
|
"screen": "voice_settings",
|
||||||
|
"params": { "tab": "commands" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:** Created broadcast object with `id`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Update Broadcast
|
||||||
|
```http
|
||||||
|
PUT /admin/broadcasts/:id
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request Body:** Partial broadcast object (same as create)
|
||||||
|
|
||||||
|
**Response:** Updated broadcast object
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Delete Broadcast
|
||||||
|
```http
|
||||||
|
DELETE /admin/broadcasts/:id
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:** `204 No Content`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Send Broadcast
|
||||||
|
```http
|
||||||
|
POST /admin/broadcasts/:id/send
|
||||||
|
```
|
||||||
|
|
||||||
|
Triggers immediate send (or schedules if `scheduledAt` is set).
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Broadcast queued for sending",
|
||||||
|
"estimatedReach": 1500
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Pause Broadcast
|
||||||
|
```http
|
||||||
|
POST /admin/broadcasts/:id/pause
|
||||||
|
```
|
||||||
|
|
||||||
|
Pauses a sending broadcast.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Broadcast paused"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Get Broadcast Metrics
|
||||||
|
```http
|
||||||
|
GET /admin/broadcasts/:id/metrics
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"targetedCount": 1500,
|
||||||
|
"sentCount": 1500,
|
||||||
|
"deliveredCount": 1420,
|
||||||
|
"openedCount": 890,
|
||||||
|
"clickedCount": 340,
|
||||||
|
"dismissedCount": 45,
|
||||||
|
"convertedCount": 120,
|
||||||
|
"deliveryRate": 94.7,
|
||||||
|
"openRate": 59.3,
|
||||||
|
"clickRate": 22.7,
|
||||||
|
"conversionRate": 8.0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Clone Broadcast
|
||||||
|
```http
|
||||||
|
POST /admin/broadcasts/:id/clone
|
||||||
|
```
|
||||||
|
|
||||||
|
Creates a copy of the broadcast as a draft.
|
||||||
|
|
||||||
|
**Response:** New broadcast object with `id`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Public Endpoints (Authenticated)
|
||||||
|
|
||||||
|
#### List In-App Messages
|
||||||
|
```http
|
||||||
|
GET /public/messages/in-app
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns active in-app messages for the authenticated user.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"messages": [
|
||||||
|
{
|
||||||
|
"id": "msg_987654321",
|
||||||
|
"broadcastId": "bc_123456789",
|
||||||
|
"title": "New Feature Announcement",
|
||||||
|
"body": "Check out our latest update!",
|
||||||
|
"style": "banner",
|
||||||
|
"priority": "high",
|
||||||
|
"ctaText": "Try it now",
|
||||||
|
"ctaUrl": "https://app.bytelyst.io/voice",
|
||||||
|
"imageUrl": "https://cdn.bytelyst.io/banner/voice.jpg",
|
||||||
|
"deepLink": {
|
||||||
|
"screen": "voice_settings",
|
||||||
|
"params": { "tab": "commands" }
|
||||||
|
},
|
||||||
|
"status": "unread",
|
||||||
|
"createdAt": "2024-01-15T10:30:00Z"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Mark Message Read
|
||||||
|
```http
|
||||||
|
POST /public/messages/:id/read
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Marked as read"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Dismiss Message
|
||||||
|
```http
|
||||||
|
POST /public/messages/:id/dismiss
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Message dismissed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Track Message Click
|
||||||
|
```http
|
||||||
|
POST /public/messages/:id/click
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Click tracked"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Surveys
|
||||||
|
|
||||||
|
### Admin Endpoints
|
||||||
|
|
||||||
|
#### List Surveys
|
||||||
|
```http
|
||||||
|
GET /admin/surveys
|
||||||
|
```
|
||||||
|
|
||||||
|
**Query Parameters:**
|
||||||
|
| Parameter | Type | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| `status` | string | Filter by status: `draft`, `active`, `paused`, `completed` |
|
||||||
|
| `limit` | integer | Max items (default: 20, max: 100) |
|
||||||
|
| `offset` | integer | Pagination offset |
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"surveys": [
|
||||||
|
{
|
||||||
|
"id": "srv_123456789",
|
||||||
|
"productId": "lysnrai",
|
||||||
|
"title": "Product Feedback Survey",
|
||||||
|
"description": "Help us improve your experience",
|
||||||
|
"status": "active",
|
||||||
|
"questionCount": 5,
|
||||||
|
"responseCount": 892,
|
||||||
|
"incentive": {
|
||||||
|
"type": "pro_days",
|
||||||
|
"amount": 7
|
||||||
|
},
|
||||||
|
"createdAt": "2024-01-10T08:00:00Z",
|
||||||
|
"updatedAt": "2024-01-15T14:30:00Z"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 12,
|
||||||
|
"limit": 20,
|
||||||
|
"offset": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Get Survey
|
||||||
|
```http
|
||||||
|
GET /admin/surveys/:id
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:** Full survey with questions
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "srv_123456789",
|
||||||
|
"productId": "lysnrai",
|
||||||
|
"title": "Product Feedback Survey",
|
||||||
|
"description": "Help us improve your experience",
|
||||||
|
"status": "active",
|
||||||
|
"questions": [
|
||||||
|
{
|
||||||
|
"id": "q1",
|
||||||
|
"type": "nps",
|
||||||
|
"text": "How likely are you to recommend us?",
|
||||||
|
"required": true,
|
||||||
|
"minValue": 0,
|
||||||
|
"maxValue": 10
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "q2",
|
||||||
|
"type": "single_choice",
|
||||||
|
"text": "What feature do you use most?",
|
||||||
|
"required": true,
|
||||||
|
"options": [
|
||||||
|
{ "id": "voice", "text": "Voice dictation", "emoji": "🎙️" },
|
||||||
|
{ "id": "keyboard", "text": "Keyboard", "emoji": "⌨️" },
|
||||||
|
{ "id": "desktop", "text": "Desktop app", "emoji": "💻" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"target": {
|
||||||
|
"platforms": ["ios", "android"],
|
||||||
|
"userSegments": ["active"]
|
||||||
|
},
|
||||||
|
"displayTrigger": {
|
||||||
|
"type": "delay_seconds",
|
||||||
|
"seconds": 30
|
||||||
|
},
|
||||||
|
"incentive": {
|
||||||
|
"type": "pro_days",
|
||||||
|
"amount": 7
|
||||||
|
},
|
||||||
|
"metrics": {
|
||||||
|
"startedCount": 1200,
|
||||||
|
"completedCount": 892,
|
||||||
|
"completionRate": 74.3
|
||||||
|
},
|
||||||
|
"createdAt": "2024-01-10T08:00:00Z",
|
||||||
|
"updatedAt": "2024-01-15T14:30:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Create Survey
|
||||||
|
```http
|
||||||
|
POST /admin/surveys
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"title": "Product Feedback Survey",
|
||||||
|
"description": "Help us improve your experience",
|
||||||
|
"questions": [
|
||||||
|
{
|
||||||
|
"id": "q1",
|
||||||
|
"type": "nps",
|
||||||
|
"text": "How likely are you to recommend us?",
|
||||||
|
"required": true,
|
||||||
|
"minValue": 0,
|
||||||
|
"maxValue": 10
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "q2",
|
||||||
|
"type": "single_choice",
|
||||||
|
"text": "What feature do you use most?",
|
||||||
|
"description": "Select your primary use case",
|
||||||
|
"required": true,
|
||||||
|
"options": [
|
||||||
|
{ "id": "voice", "text": "Voice dictation", "emoji": "🎙️" },
|
||||||
|
{ "id": "keyboard", "text": "Keyboard", "emoji": "⌨️" }
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "q3",
|
||||||
|
"type": "text_long",
|
||||||
|
"text": "What could we improve?",
|
||||||
|
"required": false,
|
||||||
|
"maxLength": 500,
|
||||||
|
"showIf": {
|
||||||
|
"questionId": "q1",
|
||||||
|
"operator": "not_equals",
|
||||||
|
"value": ["9", "10"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"target": {
|
||||||
|
"platforms": ["ios", "android"],
|
||||||
|
"userSegments": ["active"],
|
||||||
|
"percentageRollout": 100
|
||||||
|
},
|
||||||
|
"displayTrigger": {
|
||||||
|
"type": "delay_seconds",
|
||||||
|
"seconds": 30
|
||||||
|
},
|
||||||
|
"incentive": {
|
||||||
|
"type": "pro_days",
|
||||||
|
"amount": 7
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:** Created survey object with `id`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Update Survey
|
||||||
|
```http
|
||||||
|
PUT /admin/surveys/:id
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request Body:** Partial survey object
|
||||||
|
|
||||||
|
**Response:** Updated survey object
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Delete Survey
|
||||||
|
```http
|
||||||
|
DELETE /admin/surveys/:id
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:** `204 No Content`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Get Survey Metrics
|
||||||
|
```http
|
||||||
|
GET /admin/surveys/:id/metrics
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"questionStats": [
|
||||||
|
{
|
||||||
|
"questionId": "q1",
|
||||||
|
"questionType": "nps",
|
||||||
|
"responseCount": 892,
|
||||||
|
"distribution": {
|
||||||
|
"0": 12,
|
||||||
|
"1": 8,
|
||||||
|
"2": 15,
|
||||||
|
"7": 120,
|
||||||
|
"8": 200,
|
||||||
|
"9": 180,
|
||||||
|
"10": 357
|
||||||
|
},
|
||||||
|
"average": 8.2,
|
||||||
|
"npsScore": 68
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"startedCount": 1200,
|
||||||
|
"completedCount": 892,
|
||||||
|
"completionRate": 74.3,
|
||||||
|
"averageTimeSeconds": 145
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Export Survey Responses
|
||||||
|
```http
|
||||||
|
GET /admin/surveys/:id/export
|
||||||
|
```
|
||||||
|
|
||||||
|
**Query Parameters:**
|
||||||
|
| Parameter | Type | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| `format` | string | `csv` or `json` (default: `csv`) |
|
||||||
|
|
||||||
|
**Response:** File download (CSV or JSON)
|
||||||
|
|
||||||
|
CSV format:
|
||||||
|
```csv
|
||||||
|
response_id,user_id,started_at,completed_at,q1,q2,q3
|
||||||
|
resp_abc123,user_xyz,2024-01-15T10:30:00Z,2024-01-15T10:32:45Z,8,voice,Make it faster
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Public Endpoints (Authenticated)
|
||||||
|
|
||||||
|
#### Get Active Survey
|
||||||
|
```http
|
||||||
|
GET /public/surveys/active
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns the active survey for the authenticated user, if any.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "srv_123456789",
|
||||||
|
"title": "Product Feedback Survey",
|
||||||
|
"description": "Help us improve your experience",
|
||||||
|
"questions": [
|
||||||
|
{
|
||||||
|
"id": "q1",
|
||||||
|
"type": "nps",
|
||||||
|
"text": "How likely are you to recommend us?",
|
||||||
|
"required": true,
|
||||||
|
"minValue": 0,
|
||||||
|
"maxValue": 10
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"currentQuestionIndex": 0,
|
||||||
|
"incentive": {
|
||||||
|
"type": "pro_days",
|
||||||
|
"amount": 7
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Or `204 No Content` if no active survey.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Start Survey
|
||||||
|
```http
|
||||||
|
POST /public/surveys/:id/start
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"surveyStateId": "ss_987654321",
|
||||||
|
"currentQuestionIndex": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Submit Answer
|
||||||
|
```http
|
||||||
|
POST /public/surveys/:id/answers
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"questionId": "q1",
|
||||||
|
"answer": {
|
||||||
|
"type": "rating",
|
||||||
|
"value": { "value": 8 }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"currentQuestionIndex": 1,
|
||||||
|
"nextQuestionId": "q2",
|
||||||
|
"isComplete": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Complete Survey
|
||||||
|
```http
|
||||||
|
POST /public/surveys/:id/complete
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"incentiveClaimed": true,
|
||||||
|
"incentiveType": "pro_days",
|
||||||
|
"incentiveAmount": 7
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Dismiss Survey
|
||||||
|
```http
|
||||||
|
POST /public/surveys/:id/dismiss
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Survey dismissed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Types Reference
|
||||||
|
|
||||||
|
### Broadcast Status
|
||||||
|
| Status | Description |
|
||||||
|
|--------|-------------|
|
||||||
|
| `draft` | Created but not yet sent |
|
||||||
|
| `scheduled` | Scheduled for future send |
|
||||||
|
| `sending` | Currently being sent |
|
||||||
|
| `paused` | Send paused by admin |
|
||||||
|
| `completed` | Fully sent and finished |
|
||||||
|
|
||||||
|
### Message Priority
|
||||||
|
| Priority | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| `low` | Silent delivery, no badge |
|
||||||
|
| `normal` | Standard notification |
|
||||||
|
| `high` | Prominent with sound |
|
||||||
|
| `urgent` | Critical, persistent alert |
|
||||||
|
|
||||||
|
### Message Style
|
||||||
|
| Style | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| `banner` | Top/bottom banner |
|
||||||
|
| `modal` | Center dialog |
|
||||||
|
| `fullscreen` | Full-screen takeover |
|
||||||
|
| `toast` | Brief ephemeral message |
|
||||||
|
|
||||||
|
### Survey Question Types
|
||||||
|
| Type | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `single_choice` | Radio button selection |
|
||||||
|
| `multiple_choice` | Checkbox multi-select |
|
||||||
|
| `rating` | Star rating (1-5) |
|
||||||
|
| `scale` | Numeric scale |
|
||||||
|
| `nps` | Net Promoter Score (0-10) |
|
||||||
|
| `text_short` | Single line text |
|
||||||
|
| `text_long` | Multi-line textarea |
|
||||||
|
| `ranking` | Drag-to-order items |
|
||||||
|
| `dropdown` | Single select dropdown |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Responses
|
||||||
|
|
||||||
|
All errors follow this format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": {
|
||||||
|
"code": "NOT_FOUND",
|
||||||
|
"message": "Broadcast not found",
|
||||||
|
"requestId": "req_abc123"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Codes
|
||||||
|
| Code | HTTP Status | Description |
|
||||||
|
|------|-------------|-------------|
|
||||||
|
| `BAD_REQUEST` | 400 | Invalid request data |
|
||||||
|
| `UNAUTHORIZED` | 401 | Missing or invalid token |
|
||||||
|
| `FORBIDDEN` | 403 | Insufficient permissions |
|
||||||
|
| `NOT_FOUND` | 404 | Resource not found |
|
||||||
|
| `CONFLICT` | 409 | Resource already exists |
|
||||||
|
| `RATE_LIMITED` | 429 | Too many requests |
|
||||||
|
| `INTERNAL_ERROR` | 500 | Server error |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rate Limits
|
||||||
|
|
||||||
|
| Endpoint Group | Limit |
|
||||||
|
|----------------|-------|
|
||||||
|
| Admin endpoints | 100 req/min per user |
|
||||||
|
| Public endpoints | 60 req/min per user |
|
||||||
|
| Message tracking | 1000 req/min per user |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Webhooks
|
||||||
|
|
||||||
|
Events sent to configured webhook URLs:
|
||||||
|
|
||||||
|
### Broadcast Events
|
||||||
|
- `broadcast.created`
|
||||||
|
- `broadcast.sent`
|
||||||
|
- `broadcast.completed`
|
||||||
|
- `broadcast.read`
|
||||||
|
- `broadcast.clicked`
|
||||||
|
|
||||||
|
### Survey Events
|
||||||
|
- `survey.created`
|
||||||
|
- `survey.started`
|
||||||
|
- `survey.completed`
|
||||||
|
- `survey.response_submitted`
|
||||||
|
|
||||||
|
**Webhook Payload:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"event": "broadcast.clicked",
|
||||||
|
"timestamp": "2024-01-15T10:32:15Z",
|
||||||
|
"data": {
|
||||||
|
"broadcastId": "bc_123456789",
|
||||||
|
"userId": "user_xyz",
|
||||||
|
"messageId": "msg_987654321"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user