Skip to content
GGspeakGGspeak for developers

Messages

Get the message back with wait

Section titled “Get the message back with wait”

By default, POST /hooks/{id}/{token} answers 204 No Content with no body, like Discord. With ?wait=true (or ?wait=1) the response is 200 with the message that was created, including the id you need to edit or delete it later.

Janela do terminal
curl -X POST "$GGSPEAK_WEBHOOK?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"key": "inc-1", "card": {"title": "API is down", "state": "alert", "body": "Timeout on /healthz"}}'
200 OK (example)
{
  "id": "0b7c1c0e-6a35-4d6c-9f0a-3f6f2d1d9a10",
  "channel_id": "5d1d6c43-91a2-47b1-8d89-7a4b8c0f2e11",
  "author_id": null,
  "author_nickname": "Alerts",
  "body": "**API is down** · Disparou\nTimeout on /healthz",
  "pinned": false,
  "created_at_ms": 1793714520000,
  "edited_at_ms": null,
  "reactions": [],
  "rich": null,
  "attachments": [],
  "app": { "hook_id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "name": "Alerts", "icon_url": null },
  "card": {
    "title": "API is down",
    "state": "alert",
    "body": "Timeout on /healthz",
    "url": null,
    "fields": [],
    "timeline": [{ "state": "alert", "at_ms": 1793714520000 }],
    "repeat": 1,
    "mentioned_role": null
  }
}

Ids and times will differ; the fields are these. author_id is null because the author is the webhook (app), and body is the flattened markdown text that older apps and search read.

Section titled “Check the link with GET”

Some tools call the link with a GET before saving it. The response:

GET /hooks/{id}/{token}
{
  "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f",
  "name": "Alerts",
  "icon_url": null,
  "community_id": "8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d",
  "channel_id": "5d1d6c43-91a2-47b1-8d89-7a4b8c0f2e11"
}

Edit a message

Section titled “Edit a message”

PATCH /hooks/{id}/{token}/messages/{message_id} replaces the content of a message that this webhook sent. Send the whole content again; the format is detected from the body, as with POST, with no suffix; a Better Stack body isn’t read here. The response is 200 with the updated message.

Janela do terminal
curl -X PATCH "https://ggspeak.app/hooks/$ID/$TOKEN/messages/$MESSAGE_ID" \
  -H "Content-Type: application/json" \
  -d '{"card": {"title": "API is down", "state": "ok", "body": "Back up"}}'

An edited card follows the same update rule as key: the same state bumps the counter, a new state enters the timeline. Like any edit, it doesn’t light up as unread.

Two things to remember: a PATCH without card removes the card from the message, and a key in the body is ignored (the message already has its own).

Delete a message

Section titled “Delete a message”
Janela do terminal
curl -X DELETE "https://ggspeak.app/hooks/$ID/$TOKEN/messages/$MESSAGE_ID"

The response is 204 No Content.

What applies to both

Section titled “What applies to both”
  • Only messages from the webhook itself. An id that belongs to a person, to another webhook, or is invalid answers 404 with message_not_found.
  • A paused webhook answers 410 (hook_paused).
  • Both count toward the send limits.