Outbound

Events Hijinks sends to your bridge. Every one is a signed POST to the one bridge URL you set in the dashboard; the type field in the body says which event it is. Answer any 2xx within 5 seconds.

Post a message to a channel

POST

(type: message.create)

Post message in channel and remember the mapping from message.id to your chat's own message id: a later message.update names the same message.id.

Retried at +1 s and +4 s when the bridge does not answer 2xx within 5 seconds, then dropped. A retry carries the same id.

Post a message to a channel › Headers

Hijinks-Signature

string · pattern: ^t=\d+(,v1=[0-9a-fA-… · required

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Several v1= entries are allowed; any one matching is enough.

Hijinks-Event-Id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

The envelope's id. Unchanged across retries; dedupe on it.

Unique per event and unchanged across its retries; dedupe on it.

Hijinks-Workspace

WorkspaceId · uuid · required

The envelope's workspace, for routing before the body is parsed.

The Hijinks workspace, as shown in the dashboard.

Post a message to a channel › Request Body

MessageCreateEvent

id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

Unique per event and unchanged across its retries; dedupe on it.

type

const · required

Const value: message.create

workspace

WorkspaceId · uuid · required

The Hijinks workspace, as shown in the dashboard.

sequence

Sequence · int64 · min: 1 · required

Strictly increasing per workspace, so events that arrive out of order can be put back in order (an older message.update than one already applied can be skipped). Not contiguous. Taken from Hijinks' clock in microseconds, so it keeps increasing across Hijinks restarts and deploys. Below 2^53, so it fits a JSON number in every language.

createdAt

CreatedAt · date-time · required

When Hijinks created the event (ISO 8601, UTC).

expiresAt

ExpiresAt · date-time · required

When the event goes stale (ISO 8601, UTC): past it, drop the event unapplied. 60 seconds after createdAt for message.ephemeral and ping; 10 minutes for a live game's messages and the answers to commands; null — never stale — for prompts and results that stay valid for hours (self-paced rounds, word games with their own end, icebreakers, digests). Compare it with your own clock.

channel

OutboundChannel · minLength: 1 · required

A channel id your bridge sent in an inbound event — or dm:<user id> on a message.update of a message first sent by dm.create.

Message · required

Post a message to a channel › Responses

Delivered. Any other answer, or none within 5 seconds, is a failure.

No data returned

Example Request Body

{
  "id": "evt_01JA2Z7H2J3K4M5N6P7Q8R9STV",
  "type": "message.create",
  "workspace": "6f0c2b9e-8d4a-4f6b-9c1e-2a7d5e0b4c83",
  "sequence": 1760018637000001,
  "createdAt": "2026-10-09T14:03:57.000Z",
  "expiresAt": "2026-10-09T14:13:57.000Z",
  "channel": "town-square",
  "message": {
    "id": "msg_01JA2Z8KQ4M6V3XG5H7N9PRSTW",
    "kind": "game_start",
    "text": "*🧠 Trivia*\n**Starting a game…**\n\n*Film · Medium · 5 questions*\n*Started by Maya K. · First question in a few seconds*",
    "buttons": [],
    "image": null,
    "awaitsReply": false,
    "data": {
      "category": "Film",
      "difficulty": "medium",
      "questionCount": 5,
      "language": "en",
      "startedBy": "8x7tq3w5ojy1mrd9ziakh4ebfc",
      "startedByDisplayName": "Maya K."
    }
  }
}

json

application/json

Example Responses

No example specified for this content type

Replace a message Hijinks created

POST

(type: message.update)

Replace the text, buttons and image of the message you posted for message.id. channel is the channel of the original message.create — or dm:<user id> when the original was a dm.create.

A live game keeps one message: the game_start card is created, and every question, answer count, reveal and the final board arrive as updates of it. So an update can be the only copy of a question — handle kind: question here, not only on create.

An update that starts a phase (question, gotcha_bait, gotcha_reveal, time_up, game_end) is retried at +1 s and +4 s like a create, with the same id. Any other update (an answer count, a tally) is never retried: the next one supersedes it. Apply updates in sequence order, skipping one older than the last you applied. An update for an id you have not mapped may have overtaken its create's retry: hold it for up to 5 seconds, then ignore it (its create was dropped).

Replace a message Hijinks created › Headers

Hijinks-Signature

string · pattern: ^t=\d+(,v1=[0-9a-fA-… · required

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Several v1= entries are allowed; any one matching is enough.

Hijinks-Event-Id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

The envelope's id. Unchanged across retries; dedupe on it.

Unique per event and unchanged across its retries; dedupe on it.

Hijinks-Workspace

WorkspaceId · uuid · required

The envelope's workspace, for routing before the body is parsed.

The Hijinks workspace, as shown in the dashboard.

Replace a message Hijinks created › Request Body

MessageUpdateEvent

id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

Unique per event and unchanged across its retries; dedupe on it.

type

const · required

Const value: message.update

workspace

WorkspaceId · uuid · required

The Hijinks workspace, as shown in the dashboard.

sequence

Sequence · int64 · min: 1 · required

createdAt

CreatedAt · date-time · required

When Hijinks created the event (ISO 8601, UTC).

expiresAt

ExpiresAt · date-time · required

channel

OutboundChannel · minLength: 1 · required

A channel id your bridge sent in an inbound event — or dm:<user id> on a message.update of a message first sent by dm.create.

Message · required

Replace a message Hijinks created › Responses

Delivered.

No data returned

Example Request Body

{
  "id": "evt_01JA2Z8KQ4M6V3XG5H7N9PRSTX",
  "type": "message.update",
  "workspace": "6f0c2b9e-8d4a-4f6b-9c1e-2a7d5e0b4c83",
  "sequence": 1760018640000001,
  "createdAt": "2026-10-09T14:04:00.000Z",
  "expiresAt": "2026-10-09T14:14:00.000Z",
  "channel": "town-square",
  "message": {
    "id": "msg_01JA2Z8KQ4M6V3XG5H7N9PRSTW",
    "kind": "question",
    "text": "*🧠 Question 3 of 5 · Film · Medium*\n**Which film was marketed with the tagline “In space, no one can hear you scream”?**\n\n*⏱ 30 seconds to answer*",
    "buttons": [
      [
        {
          "label": "Alien",
          "action": "answer_2_0"
        }
      ],
      [
        {
          "label": "Gravity",
          "action": "answer_2_1"
        }
      ],
      [
        {
          "label": "Event Horizon",
          "action": "answer_2_2"
        }
      ],
      [
        {
          "label": "Sunshine",
          "action": "answer_2_3"
        }
      ]
    ],
    "image": null,
    "awaitsReply": false,
    "data": {
      "questionIndex": 2,
      "totalQuestions": 5,
      "category": "Film",
      "difficulty": "medium",
      "text": "Which film was marketed with the tagline “In space, no one can hear you scream”?",
      "allAnswers": [
        "Alien",
        "Gravity",
        "Event Horizon",
        "Sunshine"
      ],
      "secondsPerQuestion": 30,
      "language": "en"
    }
  }
}

json

application/json

Example Responses

No example specified for this content type

Reply that only one member should see

POST

(type: message.ephemeral)

A reply to the member who ran a command (help, settings, a leaderboard) or pressed a button — or a note for one member alone that no request asked for: their recap when a game ends, whether their guess-who guess was right. Show it to user alone in channel if your chat can; otherwise DM it, or post it.

message.id is minted for the reply but never updated.

Retried at +1 s and +4 s, then dropped.

Reply that only one member should see › Headers

Hijinks-Signature

string · pattern: ^t=\d+(,v1=[0-9a-fA-… · required

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Several v1= entries are allowed; any one matching is enough.

Hijinks-Event-Id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

The envelope's id. Unchanged across retries; dedupe on it.

Unique per event and unchanged across its retries; dedupe on it.

Hijinks-Workspace

WorkspaceId · uuid · required

The envelope's workspace, for routing before the body is parsed.

The Hijinks workspace, as shown in the dashboard.

Reply that only one member should see › Request Body

MessageEphemeralEvent

id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

Unique per event and unchanged across its retries; dedupe on it.

type

const · required

Const value: message.ephemeral

workspace

WorkspaceId · uuid · required

The Hijinks workspace, as shown in the dashboard.

sequence

Sequence · int64 · min: 1 · required

createdAt

CreatedAt · date-time · required

When Hijinks created the event (ISO 8601, UTC).

expiresAt

ExpiresAt · date-time · required

channel

OutboundChannel · minLength: 1 · required

A channel id your bridge sent in an inbound event — or dm:<user id> on a message.update of a message first sent by dm.create.

user

MemberId · minLength: 1 · required

A member's user.id, as your bridge sent it.

Message · required

Reply that only one member should see › Responses

Delivered.

No data returned

Example Request Body

{
  "id": "evt_01JA2ZB5C6D7E8F9G0H1J2K3M4",
  "type": "message.ephemeral",
  "workspace": "6f0c2b9e-8d4a-4f6b-9c1e-2a7d5e0b4c83",
  "sequence": 1760018760000005,
  "createdAt": "2026-10-09T14:06:00.000Z",
  "expiresAt": "2026-10-09T14:07:00.000Z",
  "channel": "town-square",
  "user": "8x7tq3w5ojy1mrd9ziakh4ebfc",
  "message": {
    "id": "msg_01JA2ZB5C6D7E8F9G0H1J2K3M4",
    "kind": "leaderboard",
    "text": "**🏆 Leaderboard · All time**\n\n🥇 Maya K. — 42 points (7 games)\n🥈 Leo — 30 points (5 games)\n🥉 Sam — 12 points (1 game)",
    "buttons": [],
    "image": null,
    "awaitsReply": false,
    "data": {
      "period": "all-time",
      "seasonSince": null,
      "entries": [
        {
          "externalUserId": "8x7tq3w5ojy1mrd9ziakh4ebfc",
          "displayName": "Maya K.",
          "totalScore": 42,
          "gamesPlayed": 7
        },
        {
          "externalUserId": "q1w2e3r4t5y6u7i8o9p0asdfgh",
          "displayName": "Leo",
          "totalScore": 30,
          "gamesPlayed": 5
        },
        {
          "externalUserId": "z9y8x7w6v5u4t3s2r1q0ponmlk",
          "displayName": "Sam",
          "totalScore": 12,
          "gamesPlayed": 1
        }
      ]
    }
  }
}

json

application/json

Example Responses

No example specified for this content type

Send a member a private message

POST

(type: dm.create)

Open (or reuse) a direct conversation with user and post message there: async rounds, Know Your Team prompts, reminders. Map message.id as for message.create; a later message.update for it arrives with channel: "dm:<user id>". Send button presses and typed messages in the DM back as action and message events with that same channel: "dm:<user id>" (the member's own user.id), so Hijinks knows they came from the DM: replies go back to the DM, and a typed message there answers the prompt waiting in it, with or without replyTo.

Retried at +1 s and +4 s, then dropped.

Send a member a private message › Headers

Hijinks-Signature

string · pattern: ^t=\d+(,v1=[0-9a-fA-… · required

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Several v1= entries are allowed; any one matching is enough.

Hijinks-Event-Id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

The envelope's id. Unchanged across retries; dedupe on it.

Unique per event and unchanged across its retries; dedupe on it.

Hijinks-Workspace

WorkspaceId · uuid · required

The envelope's workspace, for routing before the body is parsed.

The Hijinks workspace, as shown in the dashboard.

Send a member a private message › Request Body

DmCreateEvent

id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

Unique per event and unchanged across its retries; dedupe on it.

type

const · required

Const value: dm.create

workspace

WorkspaceId · uuid · required

The Hijinks workspace, as shown in the dashboard.

sequence

Sequence · int64 · min: 1 · required

createdAt

CreatedAt · date-time · required

When Hijinks created the event (ISO 8601, UTC).

expiresAt

ExpiresAt · date-time · required

user

MemberId · minLength: 1 · required

A member's user.id, as your bridge sent it.

Message · required

Send a member a private message › Responses

Delivered.

No data returned

Example Request Body

{
  "id": "evt_01JA2ZC7D8E9F0G1H2J3K4M5N6",
  "type": "dm.create",
  "workspace": "6f0c2b9e-8d4a-4f6b-9c1e-2a7d5e0b4c83",
  "sequence": 1760018820000006,
  "createdAt": "2026-10-09T14:07:00.000Z",
  "expiresAt": null,
  "user": "q1w2e3r4t5y6u7i8o9p0asdfgh",
  "message": {
    "id": "msg_01JA2ZC7D8E9F0G1H2J3K4M5N6",
    "kind": "async_question",
    "text": "*Question 1 · Geography · Easy*\n**What is the capital of France?**",
    "buttons": [
      [
        {
          "label": "Paris",
          "action": "async_answer_7c1e_0_0"
        }
      ],
      [
        {
          "label": "London",
          "action": "async_answer_7c1e_0_1"
        }
      ],
      [
        {
          "label": "Berlin",
          "action": "async_answer_7c1e_0_2"
        }
      ],
      [
        {
          "label": "Madrid",
          "action": "async_answer_7c1e_0_3"
        }
      ]
    ],
    "image": null,
    "awaitsReply": false,
    "data": {
      "sessionId": "7c1e",
      "questionIndex": 0,
      "category": "Geography",
      "difficulty": "easy",
      "text": "What is the capital of France?",
      "allAnswers": [
        "Paris",
        "London",
        "Berlin",
        "Madrid"
      ],
      "reportable": false
    }
  }
}

json

application/json

Example Responses

No example specified for this content type

Test event

POST

(type: ping)

Sent when someone presses "Send test event" in the dashboard. Answer 2xx; the dashboard shows the status code and latency. Never retried.

Test event › Headers

Hijinks-Signature

string · pattern: ^t=\d+(,v1=[0-9a-fA-… · required

t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Several v1= entries are allowed; any one matching is enough.

Hijinks-Event-Id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

The envelope's id. Unchanged across retries; dedupe on it.

Unique per event and unchanged across its retries; dedupe on it.

Hijinks-Workspace

WorkspaceId · uuid · required

The envelope's workspace, for routing before the body is parsed.

The Hijinks workspace, as shown in the dashboard.

Test event › Request Body

PingEvent

id

EventId · pattern: ^evt_[0-9A-HJKMNP-TV… · required

Unique per event and unchanged across its retries; dedupe on it.

type

const · required

Const value: ping

workspace

WorkspaceId · uuid · required

The Hijinks workspace, as shown in the dashboard.

sequence

Sequence · int64 · min: 1 · required

createdAt

CreatedAt · date-time · required

When Hijinks created the event (ISO 8601, UTC).

expiresAt

ExpiresAt · date-time · required

Test event › Responses

Reachable.

No data returned

Polling