Quick Start

Publish your first message to Katie speakers in under 5 minutes.

Create an account and a channel

Each channel has a unique API key that you'll use to publish messages. You can find the API key in the channel settings.

Publish a message

Send a POST request to the publish endpoint with your channel API key and message text.

Using curl

curl -X POST https://api.katiespeaker.com/v1/messaging/publish \
  -H "Content-Type: application/json" \
  -d '{
    "channel_apikey": "YOUR_CHANNEL_API_KEY",
    "message": "Hello from Katie!"
  }'

Using Python

import requests

response = requests.post(
    "https://api.katiespeaker.com/v1/messaging/publish",
    json={
        "channel_apikey": "YOUR_CHANNEL_API_KEY",
        "message": "Hello from Katie!"
    }
)

print(response.json())
# {"message_id": "abc-123-...", "channel": "5"}

Using the Python SDK

pip install katie-publisher-sdk

from katie_publisher_sdk import MessagingClient

client = MessagingClient(
    base_url="https://api.katiespeaker.com",
    channel_apikey="YOUR_CHANNEL_API_KEY"
)

result = client.publish("Hello from Katie!")
print(result)

Using the JavaScript SDK

npm install katie-publisher-sdk-js

import { MessagingClient } from 'katie-publisher-sdk-js';

const client = new MessagingClient({
  baseUrl: 'https://api.katiespeaker.com',
  channelApiKey: 'YOUR_CHANNEL_API_KEY'
});

const result = await client.publish('Hello from Katie!');
console.log(result);

Using fetch

const response = await fetch(
  "https://api.katiespeaker.com/v1/messaging/publish",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      channel_apikey: "YOUR_CHANNEL_API_KEY",
      message: "Hello from Katie!"
    })
  }
);

const data = await response.json();
console.log(data);
// { message_id: "abc-123-...", channel: "5" }

Verify delivery

A successful response returns a message_id confirming the message was accepted for processing.

{
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "channel": "5"
}

The message will be converted to audio and read aloud on every Katie speaker subscribed to the channel within seconds.

Advanced Options

TTS Override

Use the message_tts field to provide text optimized for speech. The message field is displayed on screen while message_tts is spoken aloud.

{
  "channel_apikey": "YOUR_CHANNEL_API_KEY",
  "message": "AAPL: $185.92 (+2.3%)",
  "message_tts": "Apple stock is at 185 dollars and 92 cents, up 2.3 percent."
}

Message Metadata & Filtering

Attach a meta object to messages. Subscribers can set up filters so they only hear messages that match their criteria.

{
  "channel_apikey": "YOUR_CHANNEL_API_KEY",
  "message": "Emergency maintenance scheduled",
  "meta": {
    "category": "maintenance",
    "priority": "high",
    "region": "us-east"
  }
}

Time to Live (TTL)

Set ttl_seconds to control how long a message remains valid. Messages older than the TTL won't be read aloud on speakers that come online after the message was sent. Maximum: 86,400 seconds (24 hours).

{
  "channel_apikey": "YOUR_CHANNEL_API_KEY",
  "message": "Meeting starts in 10 minutes",
  "ttl_seconds": 600
}

Broadcasting

Broadcast messages bypass all subscriber filters and are delivered to every subscriber on the channel. Use this for emergency alerts, critical announcements, or system-wide notifications.

Python SDK

client.broadcast("Emergency: server maintenance in 5 minutes")

JavaScript SDK

await client.broadcast('Emergency: server maintenance in 5 minutes');

curl

curl -X POST https://api.katiespeaker.com/v1/messaging/publish \
  -H "Content-Type: application/json" \
  -d '{
    "channel_apikey": "YOUR_CHANNEL_API_KEY",
    "message": "Emergency: server maintenance in 5 minutes",
    "meta": { "broadcast": true }
  }'

Smart Publishing (Subscriber Filters)

Fetch your channel's aggregated subscriber filters and check locally whether any subscriber would receive a message before publishing. This saves API calls and TTS costs by skipping publishes that no one would hear.