Introducing Programmable Chat
Make Your Chat Behave the Way You Want
SAMA chat just got a powerful 💪🏻 upgrade. With our new Programmable Chat feature, you can now extend conversations with your own JavaScript logic.
From real-time moderation to custom replies and content rewriting — this is a flexible way to make your chat truly interactive and context-aware, tailored entirely to your use case.
💡 What is Programmable Chat?
At its core, Programmable Chat gives you direct control over how incoming messages are processed. You write a function — we run it. The function gets full context: the user, their message, and a set of control methods (accept, resolve, reject, fetch).
With this, you can:
- Block profanity or spoilers
- Inject attachments when a keyword is detected
- Replace CAPS LOCK messages with calm lowercase
- Auto-reply to greetings like “hi” or “yo”
- …or do something completely unexpected
💻 All in real-time, and all client-side for .
✍🏻 How It Works
When a message is sent, your handler function is triggered. Here’s the basic structure:
const handler = async (message, user, accept, resolve, reject, fetch) => {
// Your logic here
};
export default await handler(env.MESSAGE, env.USER, env.ACCEPT, env.RESOLVE, env.REJECT, env.FETCH);Depending on your logic, you can:
accept()the message (send it as-is)reject("reason")to block itresolve({ message }, { isReplaceBody: true })to modify or replace it
Your code runs in a secure sandbox environment with built-in parameters and a preview mode for testing. It’s simple, fast, and safe.
🧠 Use Cases
From community safety to playful interaction, the use cases are wide-ranging:
- Moderation: Block harmful or spammy content
- Message transformation: Rewrite, redact, or reformat messages
- Auto-responses: Detect keywords like “help” and reply with guidance
- Media enrichment: Respond with images, files, or other media
- Fun customization: Auto-greet users or redact URLs
And of course — you can always experiment with your own logic 😉.
📦 Explore Examples
We’ve launched a public repo with examples to help you get started:
From spoilers to caps-lock filters, it’s a great place to start or contribute your own.
✅ Try It Now
Programmable Chat is available today for all SAMA users.
Just click the Apps button in your chat header and open code editor to start coding.
There’s a live preview mode to test your logic before saving. You’ll also see helpful error messages and full logs — so debugging is smooth and fast.
📆 Looking Ahead
We see Programmable Chat as a foundation. In the future, it could support:
- Broader access to remote APIs and external services
- Integration with select JavaScript libraries
- Support for custom runtime environments and configuration
- Support for chat events
But even today, it’s powerful enough to reshape how your chat feels and functions.
💬 Questions? Ideas? Bugs?
We’d love to hear what you build — and what you’d love to see next. Join the conversation in Discord or contribute to the GitHub repo.
Get Oleksandr Chabaniuk’s stories in your inbox
Join Medium for free to get updates from this writer.
Programmable Chat is available now. Your chat — your rules.
🔍 Examples
Here are a few simple but powerful use cases — and how they work.
1. Block profanity
const handler = async (message, user, accept, resolve, reject, fetch) => {
const prohibited = ["asshole", "fuck", "bullshit"];
if (prohibited.some(word => message.body.toLowerCase().includes(word))) {
return reject("Message blocked by moderation.");
}
return accept();
};What it does:
Scans the message for banned words and blocks the message if any are found. Otherwise, the message goes through as usual.
2. Respond to greetings
const handler = async (message, user, accept, resolve, reject, fetch) => {
const greetings = ["hi", "hello", "hey", "yo"];
if (greetings.some(g => message.body.toLowerCase().startsWith(g))) {
return resolve({ message: { body: `Hey ${user.first_name || "there"}! 👋` } });
}
return accept();
};What it does:
If the message starts with a common greeting, the bot replies with a friendly wave. Otherwise, it lets the message pass.
3. Fetch a joke from external API
const handler = async (message, user, accept, resolve, reject, fetch) => {
if (message.body.toLowerCase().includes("joke")) {
try {
const res = await fetch("https://official-joke-api.appspot.com/random_joke");
const data = await res.json();
const joke = `${data.setup} — ${data.punchline}`;
return resolve({ message: { body: joke } });
} catch (e) {
return resolve({ message: { body: "Failed to fetch a joke 😕" } });
}
}
return accept();
};What it does:
If the user mentions the word “joke”, the bot fetches a random joke from a public API and replies with it. If something fails (e.g. network error), a fallback message is shown.
ℹ️ Note:
fetchworks in production, but may fail in preview mode due to browser CORS restrictions. Always test with Save + real chat for full functionality.
📚 Documentation
Want to go deeper?
In our official documentation, you’ll find parameter reference, usage tips, editor guide, and more:
‼️We recommend reading the documentation before you start.
📌 Try SAMA
To run SAMA server locally — follow https://github.com/SAMA-Communications/sama-server. Frontend app is available at https://github.com/SAMA-Communications/sama-client.
Discover, enjoy, and all feedback is welcome. We will be thankful a lot for every GitHub star, issue, or comment!











