Update messages live

Quick start

1. 1

   Keep the callback URL

   Every webhook post and every command request comes with a callback_url for that message.

   bashCopy

   BODY='{"message_container": {"color": "blue", "loader": true, "loader_text": "Deploying…"}}'
   SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MSSGS_WEBHOOK_SECRET" | sed 's/^.* //')
   
   curl -X POST "$MSSGS_WEBHOOK_URL" -H "Content-Type: application/json" \
     -H "X-Mssgs-Signature: sha256=$SIG" -d "$BODY"
   
   # {"success": true, "message_id": "...", "callback_url": "https://mss.gs/api/v1/trigger-callback/8f14e45f-..."}

2. 2

   PUT to update

   Send the new state. The card changes in place for everyone.

   bashCopy

   curl -X PUT "$CALLBACK_URL" -H "Content-Type: application/json" \
     -d '{"message_container": {"color": "green", "title": "Deploy complete", "description": "v2.1 is live."}}'

3. 3

   DELETE to remove

   No body needed.

   bashCopy

   curl -X DELETE "$CALLBACK_URL"

Update a message

PUT JSON to the callback_url. Send only what you want to change.

Responses

How long it works

30 minutes from the moment the message was posted, or the command was used. Updating does not extend it. Deleting the message uses the URL up. Files cannot be added through an update.

Show progress

Post a card with a loader, update its sub text as the job moves on, and end on the result. The loader is a spinner with a line and a smaller line under it (loader_text, loader_sub_text).

const { callback_url } = await post({
  message_container: { color: 'blue', loader: true, loader_text: 'Deploying…', loader_sub_text: 'Step 1 of 3: building' }
});

const update = (body) => {
  return fetch(callback_url, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
};

await build();
await update({ message_container: { color: 'blue', loader: true, loader_text: 'Deploying…', loader_sub_text: 'Step 2 of 3: running migrations' } });

await migrate();
await update({
  message_container: { color: 'green', title: 'Deploy complete', description: 'v2.1 is live on production.' },
  actions: [{ type: 'url:https://ci.example.com/deploys/218', text: 'View logs', color: 'green' }]
});

Delete a message

Send DELETE to the callback_url and the message is gone for everyone. The URL cannot be used again afterwards.

Listen to a message

A stream_url is a live stream (Server-Sent Events) of what happens on your message. Open it and events arrive as they happen, each as a JSON data: line whose type says what it is:

curl -N "$STREAM_URL"

data: {"type": "reaction", "message_id": "...", "emoji": ":tada:", "action": "add", "member_guid": "...", "member": {...}, "ts": 1790000000000}

data: {"type": "action", "message_id": "...", "action_id": "approve", "action": {"id": "approve", "payload": {"deploy": 218}, ...}, "member_guid": "...", "member": {...}, "ts": 1790000004200}

data: {"type": "reply", "message_id": "...", "content": "Ship it!", "member_guid": "...", "member": {...}, "ts": 1790000009800}

event: expired
data: {}

Listening in JavaScript

const events = new EventSource(streamUrl);

// Every event arrives as a plain message; its kind is in "type".
events.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  if ((ev.type === 'action') && (ev.action_id === 'approve')) {
    startDeploy(ev.action.payload.deploy);
  }
};

// The one named event: the stream is closing.
events.addEventListener('expired', () => {
  events.close();
});

Where you get one

Errors