Receiving and responding

Every interaction has to be answered. The answer is the body of your HTTP response, within 3 seconds: { "type": …, "data": … }. After that first answer the interaction's token lets you follow up for 15 minutes.

Interaction callback types

Name	Value	Use it to
PONG	1	Answer a PING (type 1)
CHANNEL_MESSAGE_WITH_SOURCE	4	Write a message in the channel
DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE	5	Say you are working on it and write the message later
DEFERRED_UPDATE_MESSAGE	6	For a component: take note and change the message later
UPDATE_MESSAGE	7	For a component: change the message the component is on, right now
APPLICATION_COMMAND_AUTOCOMPLETE_RESULT	8	Suggest values for an option
MODAL	9	Open a form

Which types answer which interactions:

The interaction is	You may answer with
a command (2)	4, 5, 9
a component (3)	4, 5, 6, 7, 9
autocomplete (4)	8
a form (5)	4, 5, 6, 7

Anything else is refused and the member is told your answer was not acceptable.

Responding with a message

Answer with a messageJSON

{
  "type": 4,
  "data": {
    "content": "You rolled **4**.",
    "embeds": [{ "title": "d6", "color": 3145582 }],
    "components": [{
      "type": 1,
      "components": [{
        "type": 2,
        "style": 1,
        "label": "Roll again",
        "custom_id": "again"
      }]
    }],
    "allowed_mentions": { "parse": [] },
    "flags": 0
  }
}

The message is written by your bot in the channel where the member used the command, and it shows who asked ("ada used /roll") above it. The fields are those of creating a message. By default an answer may ping members only: set allowed_mentions to allow more. Your bot needs Send Messages in the channel, or the member is told your answer failed: check app_permissions first.

Ephemeral messages

Set flags to 64 (EPHEMERAL) and only the member who acted sees the answer, with a note that says so. It is never stored: it is told to that member's program and is gone when they close Moymo, so use it for confirmations, errors and anything private, not for what should be remembered.

Deferred responses

If you need more than 3 seconds, answer { "type": 5 } at once. The channel shows "Your app is thinking…" (or, with { "type": 5, "data": { "flags": 64 } }, only the member sees it). Then, within 15 minutes, send the real answer with a followup or edit the original: the "thinking" message becomes the answer. If you never do, it says The application did not respond.

RequestPATCH/webhooks/{application.id}/{interaction.token}/messages/@original

curl

curl -X PATCH \
  "https://moymo.net/api/app/v1/webhooks/$APP_ID/$INTERACTION_TOKEN/messages/@original" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Done. It took a while." }'

JavaScript

await fetch(
  `https://moymo.net/api/app/v1/webhooks/${appId}/${interaction.token}/messages/@original`,
  {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ content: 'Done. It took a while.' })
  }
)

Components: update the message

A press of a button can change the message the button is on: answer { "type": 7, "data": { "content": "Count: 1" } }. Only what is in data changes (leave out components to keep the buttons, send [] to remove them). { "type": 6 } acknowledges the press without changing anything yet; edit @original later.

Your answer is also how you keep a press from looking like a failure: a component interaction that is not answered in time shows the member an error.

Responding with autocomplete

For an interaction of type 4, answer with up to 25 choices:

Answer with suggestionsJSON

{
  "type": 8,
  "data": {
    "choices": [
      { "name": "Hades", "value": "hades" },
      { "name": "Hades II", "value": "hades-2" }
    ]
  }
}

A choice has a name of 1 to 100 characters and a value that is text of at most 100 characters or a number. The member's program asks while they type (not more than a few times a second), so answer quickly and cache.

Responding with a modal

Answer a command or a component with { "type": 9, "data": { "custom_id": …, "title": …, "components": [ … ] } } and the member sees a form. When they send it you get an interaction of type 5. See Using modals.

Followups and edits

With the token, for 15 minutes, and without a bot token:

Create followup	Another message. After a deferred response, the first one is the answer
Edit response	Change @original, or a message you wrote
Delete response

What the member is told

Your application's mistakes reach the person who used it, in words:

What happened	They are told
Your endpoint did not answer in 3 seconds	The application did not respond in time
It answered with an error status or something that is not JSON	The application answered with an error
Your answer was of a type that does not fit, or its message was not acceptable	The application's answer is not acceptable, and why
Your bot may not write in the channel	The application's answer is not acceptable, and why (check app_permissions first)
No endpoint is set or verified	The application is not set up to receive commands