allows topicrecipient for broadcasts and updates some descriptions

openapi/spec/openapi.json

@@ -1109,14 +1109,14 @@
  "title": { "$ref": "#/components/schemas/Notification/properties/title" },
  "category": { "$ref": "#/components/schemas/Notification/properties/category" },
  "topic": { "$ref": "#/components/schemas/Notification/properties/topic" },
- "created_at": { "type": "string", "format": "date-time","nullable": false },
- "updated_at": { "type": "string", "format": "date-time","nullable": false },
+ "created_at": { "type": "string", "format": "date-time", "nullable": false },
+ "updated_at": { "type": "string", "format": "date-time", "nullable": false },
  "sent_at": { "type": "string", "format": "date-time", "nullable": true },
  "read_at": { "type": "string", "format": "date-time", "nullable": true },
  "seen_at": { "type": "string", "format": "date-time", "nullable": true },
  "archived_at": { "type": "string", "format": "date-time", "nullable": true },
  "discarded_at": { "type": "string", "format": "date-time", "nullable": true },
- "status": { "type":  "string", "enum": ["unseen", "unread", "read", "archived"] },
+ "status": { "type": "string", "enum": ["unseen", "unread", "read", "archived"] },
  "recipient": {
  "type": "object",
  "properties": {
@@ -1126,7 +1126,7 @@
  },
  "deliveries": {
  "type": "array",
- "items": { "$ref":  "#/components/schemas/Delivery" },
+ "items": { "$ref": "#/components/schemas/Delivery" },
  "nullable": false
  }
  }
@@ -1514,14 +1514,14 @@
  "content": {
  "application/json": {
  "example": {
-  "errors": [
-  {
-  "code": "user_not_found",
-  "message": "User not found",
-  "suggestion": "Please provide the correct 'X-MAGICBELL-USER-EMAIL' or 'X-MAGICBELL-USER-EXTERNAL-ID' header to identify the user.",
-  "help_link": "https://magicbell.com/docs/rest-api/authentication"
-  }
-  ]
+ "errors": [
+ {
+ "code": "user_not_found",
+ "message": "User not found",
+ "suggestion": "Please provide the correct 'X-MAGICBELL-USER-EMAIL' or 'X-MAGICBELL-USER-EXTERNAL-ID' header to identify the user.",
+ "help_link": "https://magicbell.com/docs/rest-api/authentication"
+ }
+ ]
  }
  }
  }
@@ -2755,6 +2755,7 @@
  },
  "Recipient": {
  "type": "object",
+ "description": "A recipient is a user, a segment (specified by matches), or a topic. For guidance on selecting a primary identifier, see https://www.magicbell.com/docs/choosing-an-identifier",
  "additionalProperties": true,
  "properties": {
  "email": {
@@ -2764,12 +2765,16 @@
  },
  "external_id": {
  "type": "string",
- "description": "A unique string that MagicBell can utilize to uniquely identify the user. We recommend setting this attribute to the ID of the user in your database. Provide the external id if the user's email is unavailable.",
+ "description": "The unique identifier from your database for the recipient.",
  "nullable": true
  },
  "matches": {
  "type": "string",
  "description": "An SQL-like expression to match users by their stored attributes. Set it to \"*\" to send a notification to all users."
+ },
+ "topic": {
+ "type": "object",
+ "description": "The topic to send the notification to. It can be a user, a segment or a group."
  }
  }
  },
@@ -2780,6 +2785,7 @@
  "Broadcast": {
  "type": "object",
  "additionalProperties": false,
+ "description": "A broadcast is a precursor to a notification. When you specify multiple recipients, MagicBell creates a notification for each recipient and delivers it to them based on their preferences.",
  "properties": {
  "id": {
  "type": "string",
@@ -2814,13 +2820,13 @@
  },
  "topic": {
  "type": "string",
- "description": "Topic the notification belongs to. This is useful to create threads.",
+ "description": "Topic the notification belongs to. This is useful for creating threads or offering topic level unsubscriptions.",
  "nullable": true,
  "maxLength": 100
  },
  "custom_attributes": {
  "type": "object",
- "description": "Set of key-value pairs that you can attach to a notification, 6KB at maximum. It accepts objects for the value of a key.\n\nYou can use it to share data between channels or to render a custom UI.",
+ "description": "Nested key-value attributes that can be used for rendering in templates in MagicBell or third-party providers. Limited to 256KB - please see Overrides for another way to send channel specific data.",
  "nullable": true,
  "additionalProperties": true
  },
@@ -2841,6 +2847,7 @@
  "type": "array",
  "items": {
  "anyOf": [
+ { "$ref": "#/components/schemas/TopicRecipient" },
  { "$ref": "#/components/schemas/MatchesRecipient" },
  { "$ref": "#/components/schemas/EmailRecipient" },
  { "$ref": "#/components/schemas/ExternalIdRecipient" }
@@ -3516,6 +3523,27 @@
  }
  }
  },
+ "TopicRecipient": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["topic"],
+ "properties": {
+ "topic": {
+ "type": "object",
+ "description": "The topic to deliver to.",
+ "nullable": false,
+ "required": ["subscribers"],
+ "additionalProperties": false,
+ "properties": {
+ "subscribers": {
+ "type": "boolean",
+ "description": "Setting this property triggers delivery to topic subscribers, respecting their unsubscriptions.",
+ "nullable": false
+ }
+ }
+ }
+ }
+ },
  "MatchesRecipient": {
  "type": "object",
  "additionalProperties": false,
@@ -3563,9 +3591,9 @@
  "nullable": false,
  "items": {
  "type": "array",
-  "items": {
-  "type": "integer"
-  }
+ "items": {
+ "type": "integer"
+ }
  }
  },
  "labels": {
@@ -3591,13 +3619,7 @@
  },
  "operation": {
  "type": "string",
- "enum": [
- "count",
- "avg",
- "sum",
- "min",
- "max"
- ]
+ "enum": ["count", "avg", "sum", "min", "max"]
  }
  }
  }
@@ -3612,10 +3634,7 @@
  },
  "type": {
  "type": "string",
- "enum": [
- "timestamp",
- "string"
- ]
+ "enum": ["timestamp", "string"]
  }
  }
  }