# Discord API

{% hint style="info" %}
All the endpoints used in the guide are available at the [Discord Developer Documentation](https://discord.com/developers/docs/intro).
{% endhint %}

If you are new to BotWiz, and have not yet added your bot: [click here](https://docs.botwiz.dev/docs/getting-started/adding-token-to-botwiz) to learn how!\
If you have any questions throughout or get stuck, feel free to visit our [Support Server](https://discord.gg/5qRpsctzjB).

### Finding Endpoints

Head to the [Discord Developers Documentation](https://discord.com/developers/docs/intro) and have a look around the page and get comfortable with it. \
The search bar on the left hand side is your best friend! (Ctrl + k)

<figure><img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2F4J6aV1nhYwLVAnwLFS0Q%2Fss.jpg?alt=media&#x26;token=5112d7d5-aee4-484e-a8dd-606d695ba2fd" alt=""><figcaption><p>Image shows a highlighted box around the search bar.</p></figcaption></figure>

### Examples

<details>

<summary>Get Channel Messages</summary>

**All the info about this API endpoint can be found here:**\
**🔗** [**https://discord.com/developers/docs/resources/channel#get-channel-messages**](https://discord.com/developers/docs/resources/channel#get-channel-messages)

To get channel messages from a channel in your discord server, we need to use the following endpoint:\ <mark style="color:blue;">`GET`</mark>` ``https://discord.com/api/v10/channels/`<mark style="color:orange;">`CHANNEL-ID`</mark>`/messages`

You will need to replace <mark style="color:orange;">`CHANNEL-ID`</mark> with your guild channel ID.

#### API Name

For this guide our name for the API block will be **get\_msg**.

The variable list at the bottom of the API setup page should now display the following:

* `{api_get_msg[response]}`
* `{api_get_msg[status-code]}`
* `{api_get_msg[status-text]}`

### HTTP Header

We now need to authorise our discord bot for discord to let us send a request to the endpoint.

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FBUfOsAVGc94rAK56H2Zo%2Fimage.png?alt=media&#x26;token=8c9a2984-afaf-41ed-aae8-301c46388864" alt="" data-size="original">

You **don't** need to replace <mark style="color:green;">`{bot_token}`</mark>with your actual bot token, as this variable will grab it automatically.

### Test request

If you have completed all the steps above, head to the **Test Request** tab, and press "Test". You should now see the latest 100 messages in your channel.

You will also notice that is displays **0 - 99** responses, this is because the response is an **Array** and array indexes start at 0.

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FH5cS4lcBf6XhvHdHDwIY%2Fimage.png?alt=media&#x26;token=14671942-42fa-4fa4-b2b5-34886b52e766" alt="" data-size="original">

The test request will display an **Invalid Form Body** error if you have any variables in your URL, as the test request only accepts RAW input from all fields in the API request.

### Getting the latest message

To get the latest message that was sent in the channel you have chosen, head to your **URL Parameters** and add the following:

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FBRyKp7jNufGrbgtW3iem%2Fimage.png?alt=media&#x26;token=a2dd6ef4-5ba4-42b2-b39f-d2ff5a97276e" alt="" data-size="original">

Head back to your test request and click on "Test" again, you will now see only 1 response (the **0 index** response).

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FhP6p1FzNLIblNF45gmdt%2Fimage.png?alt=media&#x26;token=e0ca72a4-c7bc-4ed1-9585-d0e390831b95" alt="" data-size="original">

### Displaying the latest message

To display the latest message that was sent in that channel, create a new message component. For this guide we will be using an embed component.

In our **Embed Description** we will add the variable `{api_get_msg[response.0.content]}`. This will display the latest message that was sent in the channel.

### Displaying the ID of the message

To display the ID of the latest message, add the variable `{api_get_msg[response.0.id]}` into your embed / message description.

</details>

<details>

<summary>Create a Message</summary>

**All the info about this API endpoint can be found here:**\
**🔗** [**https://discord.com/developers/docs/resources/channel#create-message**](https://discord.com/developers/docs/resources/channel#create-message)

To get channel messages from a channel in your discord server, we need to use the following endpoint:\ <mark style="color:green;">`POST`</mark>` ``https://discord.com/api/v10/channels/`<mark style="color:orange;">`CHANNEL-ID`</mark>`/messages`

You will need to replace <mark style="color:orange;">`CHANNEL-ID`</mark> with your guild channel ID.

#### API Name

For this guide our name for the API block will be **post\_msg**.

The variable list at the bottom of the API setup page should now display the following:

* `{api_post_msg[response]}`
* `{api_post_msg[status-code]}`
* `{api_post_msg[status-text]}`

### HTTP Header

We now need to authorise our discord bot for discord to let us send a request to the endpoint.

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FBUfOsAVGc94rAK56H2Zo%2Fimage.png?alt=media&#x26;token=8c9a2984-afaf-41ed-aae8-301c46388864" alt="" data-size="original">

You **don't** need to replace <mark style="color:green;">`{bot_token}`</mark>with your actual bot token as this variable will grab it automatically.

### Request Body

The request body allows us to add JSON data to send to the request, enabling us to specify the details of the action we want to perform. In the context of the Discord API the request body can be used to define various parameters such as the content of a message.

To be able to create a plain text message, all we need to add into the request body is the content, see the table below.

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FPRraeHwAXP1cpFk2p3LF%2Fimage.png?alt=media&#x26;token=35908a1d-8236-4b6f-a5ff-ee027101c9f9" alt="" data-size="original">

### Test Request

If you have completed all the steps above, head to the **Test Request** tab, and press "Test". You should know see a **Message Object**, and if you check your discord channel, you should see a message has been sent!

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FmhRl5pQqI6eyOlEqLpPF%2Fimage.png?alt=media&#x26;token=421d71b0-2f36-4ffb-ae32-cc9249e6dea4" alt="" data-size="original">

### Request body (Embed)

To send embed messages via Discord API it's slightly different than a plain text message. The key is changed to **embeds** and the value becomes an array of **embed objects.** That simply just means the embeds parameter can process multiple values, instead of just 1.

If you've created any embed webhook with JSON data, it's exactly the same as that.

To send an embed message that has a description of "My first API embed message" with a footer of "Sent with Botwiz.dev" follow the structure below:

**"color"** has to be a decimal number, it does not accept hexadecimal values (#fffff, #222). You can use a "**Hexadecimal to decimal**" converter to convert the hex value to decimal.

![](https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FABXUbgaKdEQVkVqFSCyv%2Fimage.png?alt=media\&token=5d2488f9-ebaa-447b-a224-7f1b37379427)![](https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FNbgF6y81iVNgFM8PvT5Z%2Fimage.png?alt=media\&token=bf9cafaa-5f65-48c2-8342-00ce0b61184a)

<img src="https://3071155663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3kWzjw3glf7IkiBD8sfd%2Fuploads%2FnWuWnq71UzDJ6D9VpU1t%2Fimage.png?alt=media&#x26;token=b18c2b1f-cf48-4872-b662-cf5f7df0f139" alt="" data-size="original">

To get JSON data for an embed you want to create, you can build the embed through our free [embed builder ](https://botwiz.dev/free-tools/discord-embed-builder)tool and retrieve the JSON data by pressing **View JSON**.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.botwiz.dev/botwiz-guides/botwiz-guides-1/using-apis/discord-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
