Add Chat to Your App in 5 Minutes

Step 1 — Create an app (get an API key + secret)

Create a tenant and store the returned api_key and api_secret. The secret is only shown once.

curl -sS -X POST https://heyyo-production-c881.up.railway.app/api/apps \
  -H 'Content-Type: application/json' \
  -d '{"name":"Acme Chat"}'

Step 2 — Mint a user token (JWT)

Tokens are minted on your backend using your app credentials. You’ll use the returned JWT for REST and WebSocket (Socket.IO).

curl -sS -X POST https://heyyo-production-c881.up.railway.app/api/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key":"cb_...",
    "api_secret":"cbs_...",
    "user_id":"user-123",
    "display_name":"Jane Doe"
  }'

Step 3 — Create a channel

Channels are the primary grouping primitive for messages. Most apps start with something like general.

curl -sS -X POST https://heyyo-production-c881.up.railway.app/api/channels \
  -H 'Authorization: Bearer <USER_JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"general","type":"messaging"}'

Step 4 — Send a message (REST)

Once you have a channel ID, sending messages via REST is a single request.

curl -sS -X POST \
  https://heyyo-production-c881.up.railway.app/api/channels/<CHANNEL_ID>/messages \
  -H 'Authorization: Bearer <USER_JWT>' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello from REST"}'

Same flow with the TypeScript SDK (@heyyo/sdk)

Prefer a higher-level client? The SDK wraps the same endpoints and also connects a Socket.IO client for real-time events.

import { HeyyoClient } from '@heyyo/sdk';

const client = new HeyyoClient({
  apiUrl: 'https://heyyo-production-c881.up.railway.app',
  token: '<USER_JWT>',
});

client.connect();

const channel = await client.channels.create('general', { type: 'messaging' });
const message = await client.messages.send(channel.id, 'Hello from the SDK');

client.on('message.new', (m) => {
  console.log('message.new', m.id, m.text);
});

What’s next?

• Use presence + typing indicators to make your UI feel alive.
• Add reactions + threads to reduce noise in busy channels.
• Ship a full UI using @heyyo/react (or build your own on top of the primitives).

Note: examples above target the production deployment. For local development, replace the base URL with http://localhost:4000.