💬

Chat Integration

Build chat bots, moderation tools, and interactive experiences using the Velora Chat API.

Overview

The Velora Chat API allows your application to:

•Send chat messages on behalf of authenticated users
•Apply message effects like glow, rainbow, galaxy, and gigantify
•Reply to specific messages with threading
•Build interactive chat bots and alert systems

Required Scopes

Scope	Purpose	Rate Limit
`chat:read`	Read chat messages and history	-
`chat:write`	Send chat messages	30 req/min
`chat:moderate`	Delete messages, timeout, ban users	60 req/min

Send Chat Message

POST/api/integrations/oauth/chat/:channelId/messages

Send a chat message to a specific channel. The message will be sent as the authenticated user.

URL Parameters

Parameter	Description
`channelId`	The user ID of the channel to send the message to

Request Body

Field	Type	Description
`message`	string	The message content (max 500 characters)
`effect`	string?	Message effect: glow, galaxy, rainbow, gigantify
`effectColor`	string?	Hex color for the effect (e.g., #ff6b6b)
`replyTo`	object?	Reply to a specific message (see below)

replyTo Object

Field	Type	Description
`messageId`	string	ID of the message being replied to
`username`	string	Username of the original message author
`snippet`	string	Preview of the original message (max 100 chars)

Example Request

curl -X POST https://api.velora.tv/api/integrations/oauth/chat/user-uuid-123/messages \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello from my integration!",
    "effect": "glow",
    "effectColor": "#ff6b6b"
  }'

Response

{
  "success": true,
  "messageId": "msg-uuid-456"
}

Message Effects

Velora chat supports special message effects that make messages stand out:

glow

Adds a subtle glow around the message text

"effect": "glow", "effectColor": "#ff6b6b"

CSS: text-shadow: 0 0 10px {effectColor}

galaxy

Animated starfield background behind the message

"effect": "galaxy"

Renders animated particles behind the message container

rainbow

Cycling rainbow colors on the text

"effect": "rainbow"

CSS: Animated gradient with -webkit-background-clip: text

gigantify

Large bouncing text animation

"effect": "gigantify"

CSS: font-size: 2em with bounce animation

Replying to Messages

You can reply to specific messages by including the replyTo object:

curl -X POST https://api.velora.tv/api/integrations/oauth/chat/user-uuid-123/messages \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Thanks for the follow!",
    "replyTo": {
      "messageId": "original-msg-uuid",
      "username": "newviewer",
      "snippet": "Just followed, love your content!"
    }
  }'

Tip: The snippet field is displayed as a preview of the original message in the reply UI.

Complete Example

Here's a complete JavaScript example for building a simple chat bot:

// Velora Chat Bot Example

const VELORA_API = 'https://api.velora.tv/api/integrations/oauth';

class VeloraChatBot {
  constructor(accessToken) {
    this.accessToken = accessToken;
  }

  async sendMessage(channelId, message, options = {}) {
    const response = await fetch(
      `${VELORA_API}/chat/${channelId}/messages`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          message,
          effect: options.effect,
          effectColor: options.effectColor,
          replyTo: options.replyTo,
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Failed to send message');
    }

    return response.json();
  }

  // Send a welcome message with glow effect
  async welcomeUser(channelId, username) {
    return this.sendMessage(
      channelId,
      `Welcome to the stream, @${username}! 🎉`,
      { effect: 'glow', effectColor: '#4ecdc4' }
    );
  }

  // Send a follow thank you with rainbow
  async thankFollower(channelId, username) {
    return this.sendMessage(
      channelId,
      `Thank you for the follow, @${username}! ❤️`,
      { effect: 'rainbow' }
    );
  }

  // Send a sub alert with gigantify
  async celebrateSub(channelId, username, months) {
    const emoji = months > 1 ? '🏆' : '🎊';
    return this.sendMessage(
      channelId,
      `${emoji} @${username} just subscribed for ${months} month(s)! ${emoji}`,
      { effect: 'gigantify' }
    );
  }

  // Reply to a message
  async replyTo(channelId, originalMessage, reply) {
    return this.sendMessage(channelId, reply, {
      replyTo: {
        messageId: originalMessage.id,
        username: originalMessage.username,
        snippet: originalMessage.content.substring(0, 100),
      },
    });
  }
}

// Usage Example
const bot = new VeloraChatBot('your_oauth_access_token');
const channelId = 'streamer-user-id';

// Welcome a new viewer
bot.welcomeUser(channelId, 'NewViewer123')
  .then(result => console.log('Message sent:', result.messageId))
  .catch(err => console.error('Error:', err.message));

// React to events from webhooks
async function handleWebhookEvent(event) {
  if (event.event === 'user.follow') {
    await bot.thankFollower(
      event.data.channel.id,
      event.data.follower.username
    );
  }

  if (event.event === 'channel.subscribe') {
    await bot.celebrateSub(
      event.data.channel.id,
      event.data.subscriber.username,
      event.data.months
    );
  }
}

Error Handling

Status	Meaning
`401`	Invalid or expired access token
`403`	User is banned/timed out in the channel, or missing chat:write scope
`404`	Channel not found
`429`	Rate limit exceeded (30 messages/minute for chat:write)