Post Announcement API

This endpoint allows you to create and publish a new announcement.

Endpoint

POST /api/announcement

Authentication

The API uses an API key to authenticate access. You may insert the provided API key in your requests header Authorization like the following:

Authorization: Bearer {API key}

Replace YOUR_API_KEY with the actual API key provided to you.

Headers

• Content-Type: application/json
• Accept: application/json

Request Body

Send a JSON object with the following properties:

Property	Type	Required	Description
user_id	integer	Yes	The ID of the user creating the announcement.
content	string	Yes	The main content of the announcement. Can include HTML, which will be sanitized.
subscriptions	array of integers	Yes	An array of subscription IDs to which this announcement will be sent.
title	string	No	The title of the announcement. If not provided, one will be generated from the content.
announcement_type	integer	No	The ID of the announcement type.
send_email	boolean	No	Whether to send this announcement via email. Defaults to false if not provided.
send_sms	boolean	No	Whether to send this announcement via SMS. Defaults to false if not provided.
send_push	boolean	No	Whether to send this announcement as a push notification. Defaults to false if not provided.
suppressed_subscriptions	array of integers	No	An array of subscription IDs that should not receive this announcement.
hidden	boolean	No	Whether this announcement should be hidden. Defaults to false if not provided.
chat_room_ids	array of integers	No	An array of up to 50 room IDs. The announcement is also posted into the chat of each room as a highlighted message from the user in user_id.

Example Request

Copy

{
  "user_id": 1,
  "content": "<p>We are excited to announce our new product launch!</p>",
  "subscriptions": [1, 2, 3],
  "title": "New Product Launch",
  "announcement_type": 1,
  "send_email": true,
  "send_push": true,
  "send_sms": false,
  "suppressed_subscriptions": [4],
  "hidden": false,
  "chat_room_ids": [12, 15]
}

Response

Success Response

Code: 200 OK

Content example:Copy

{
  "message": "Announcement created and published successfully",
  "announcement": {
    "id": 123,
    "content": "<p>We are excited to announce our new product launch!</p>",
    "title": "New Product Launch",
    "type": {
      "id": 1,
      "label": "Product Update",
      "label_color": "#00ff00"
    },
    "subscriptions": [
      {"id": 1, "name": "Premium Subscribers"},
      {"id": 2, "name": "Regular Subscribers"},
      {"id": 3, "name": "Beta Testers"}
    ],
    "email": true,
    "sms": false,
    "push": true,
    "published": true,
    "hidden": false,
    "chat_room_ids": [12, 15],
    "created_at": "2023-06-15T10:00:00Z",
    "updated_at": "2023-06-15T10:00:00Z"
  }
}

Error Responses

Code: 422 Unprocessable Entity

Content example:Copy

{
  "errors": {
    "content": [
      "The content field is required."
    ],
    "subscriptions": [
      "The subscriptions field is required."
    ]
  }
}

Code: 401 Unauthorized

Content example:Copy

{
  "message": "Unauthenticated."
}

Notes

• The content field will be sanitized to remove potentially malicious HTML.
• Make sure all subscription IDs provided in subscriptions and suppressed_subscriptions exist in the system.
• The announcement will be immediately published upon creation.
• When chat_room_ids is provided, each room receives the announcement in its chat once. A room whose chat is linked to another room posts into that room’s chat, and rooms with the chat panel hidden still receive it. If posting to one room fails, the announcement is still published and the other rooms still receive it.
• Leave out chat_room_ids (or send an empty array) to publish without posting to chat. Every room ID must belong to an existing room.