Recipes
Common tasks with the Church Chat API, start to finish.
Each recipe assumes these are set, and that the bot has been added to the chat. See API tokens to get a token, and the API reference for every request, paging and errors.
export CHURCH_CHAT_API="https://api.churchchat.tentmaking.com/api/v1"
export CHURCH_CHAT_TOKEN="ccb_..."The examples use jq to build request bodies and pull values out of responses.
Find your chats
curl -sG "$CHURCH_CHAT_API/channel-memberships/mine" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
--data-urlencode include=channel \
| jq '.included[] | select(.type == "channel") | {id, name: .attributes.name}'Use a chat’s id as CHANNEL_ID in the recipes below.
A repeating chat has a new id for each date, so keep track of it by its group_id
instead. See chats in the API reference.
Post a message
jq -n --arg channel "$CHANNEL_ID" '{data: {type: "message", attributes: {
channel_id: $channel,
body: "Service moves to 11am",
client_ref: "service-time-2026-11-15"
}}}' \
| curl -s "$CHURCH_CHAT_API/messages" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--data @- \
| jq -r '.data.id'body is Markdown. client_ref is optional, and makes it safe to retry: repeating one returns the
original message instead of posting again.
Reply in a thread
Post with thread_root_id set to the message you’re replying to:
jq -n --arg channel "$CHANNEL_ID" --arg root "$MESSAGE_ID" '{data: {type: "message", attributes: {
channel_id: $channel,
thread_root_id: $root,
body: "Thanks, added to the list."
}}}' \
| curl -s "$CHURCH_CHAT_API/messages" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--data @-Read a thread with GET /messages/thread/:id.
Edit or delete a message
A bot can only change its own messages.
jq -n --arg id "$MESSAGE_ID" '{data: {type: "message", id: $id, attributes: {
body: "Service moves to 11:30am"
}}}' \
| curl -s -X PATCH "$CHURCH_CHAT_API/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--data @-
curl -s -X DELETE "$CHURCH_CHAT_API/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN"React to a message
jq -n --arg channel "$CHANNEL_ID" --arg message "$MESSAGE_ID" '{data: {type: "reaction", attributes: {
channel_id: $channel,
message_id: $message,
emoji: "🙏"
}}}' \
| curl -s "$CHURCH_CHAT_API/reactions" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--data @- \
| jq -r '.data.id'Pass the returned id to DELETE /reactions/:id to take it back.
Read recent messages
curl -sG "$CHURCH_CHAT_API/messages/by-channel/$CHANNEL_ID" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
--data-urlencode "page[limit]=20" \
--data-urlencode include=attachments \
| jq '.data[] | {id, author: .attributes.author_name, body: .attributes.body}'Messages come newest first. Replies aren’t listed here, so check reply_count and read the thread
for those.
Catch up on what’s new
If you can’t receive webhooks, remember the newest message id you’ve seen and walk back to it. Message ids are ordered by time.
const { CHURCH_CHAT_API, CHURCH_CHAT_TOKEN } = process.env;
const headers = { Authorization: `Bearer ${CHURCH_CHAT_TOKEN}` };
async function messagesSince(channelId, lastSeenId) {
const found = [];
let url = `${CHURCH_CHAT_API}/messages/by-channel/${channelId}?page[limit]=100`;
while (url) {
const response = await fetch(url, { headers });
if (!response.ok) throw new Error(`Church Chat answered ${response.status}`);
const page = await response.json();
for (const message of page.data) {
if (lastSeenId && message.id <= lastSeenId) return found.reverse();
found.push(message);
}
url = page.links.next;
}
return found.reverse();
}Run it on a schedule, and store the newest id it returns. Without a stored id, it reads the chat’s whole history.
List who’s in a chat
curl -sG "$CHURCH_CHAT_API/channel-memberships/by-channel/$CHANNEL_ID" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
--data-urlencode "page[limit]=200" \
| jq -r '.data[].attributes | "\(.user_name) (\(.role))"'Where a chat hides its members, the list only has the bot itself.
Upload a file and send it
Upload the bytes first, then name the result when you post. The API reference has the size limits.
ATTACHMENT_ID=$(curl -s "$CHURCH_CHAT_API/attachments?channel_id=$CHANNEL_ID&filename=report.pdf" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @report.pdf \
| jq -r '.id')
jq -n --arg channel "$CHANNEL_ID" --arg file "$ATTACHMENT_ID" '{data: {type: "message", attributes: {
channel_id: $channel,
body: "This week'"'"'s report",
attachment_ids: [$file]
}}}' \
| curl -s "$CHURCH_CHAT_API/messages" \
-H "Authorization: Bearer $CHURCH_CHAT_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--data @-Unlike other responses, the upload’s isn’t wrapped in data. To change your mind before sending,
use DELETE /attachments/:id.
To download a file, send your token to
GET /api/media/:id.
Answer messages from a webhook
This small server answers anyone who starts a message with !hours, in a thread. First
add an outgoing webhook to the bot for message.created, and
save its signing secret as WEBHOOK_SECRET. It needs Node 20 or later and nothing else.
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const { CHURCH_CHAT_API, CHURCH_CHAT_TOKEN, WEBHOOK_SECRET } = process.env;
function verify(rawBody, header = "") {
const [, timestamp, signature] = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header) ?? [];
if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = createHmac("sha256", WEBHOOK_SECRET)
.update(`${timestamp}.${rawBody}`)
.digest();
const given = Buffer.from(signature, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
async function answer(message) {
await fetch(`${CHURCH_CHAT_API}/messages`, {
method: "POST",
headers: {
Authorization: `Bearer ${CHURCH_CHAT_TOKEN}`,
"Content-Type": "application/vnd.api+json",
},
body: JSON.stringify({
data: {
type: "message",
attributes: {
channel_id: message.channel_id,
thread_root_id: message.thread_root_id ?? message.id,
body: "We meet Sundays at 10am.",
client_ref: `hours-${message.id}`,
},
},
}),
});
}
createServer(async (request, response) => {
const chunks = [];
for await (const chunk of request) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString();
if (!verify(rawBody, request.headers["x-churchchat-signature"])) {
response.writeHead(401).end();
return;
}
response.writeHead(200).end();
const event = JSON.parse(rawBody);
if (event.type !== "message.created") return;
const { message } = event.data;
if (message.author_bot_kind === null && message.body?.startsWith("!hours")) {
await answer(message);
}
}).listen(3000);Answering before doing the slow work keeps within the 10 second limit. Checking author_bot_kind
stops two bots from answering each other forever, and client_ref makes a retried event safe.
Post from a script without a bot
If all you need is to post into one chat, an incoming webhook needs no token or JSON:API. It’s a good fit for alerts and scheduled reminders.