Discord API
La API de Discord está estructurada en torno a dos capas fundamentales: una API REST/HTTPS, orientada a la gestión de operaciones generales, y una conexión WebSocket segura y persistente, utilizada para el envío y la suscripción a eventos en tiempo real. El uso más habitual de la API de Discord consiste en ofrecer servicios o proporcionar acceso a plataformas mediante la utilización de la API OAuth2.
Enlaces base
Stable: https://discord.com/api
PTB: https://ptb.discord.com/api
Canary:https://canary.discord.com/api Versionado de la API
Algunas versiones de la API y de la gateway ya no funcionan y se encuentran marcadas como "descontinuadas" en la tabla inferior. Intentar utilizar estas versiones resultará en un error 400 Bad Request.
Discord tiene diferentes versiones de su API. Es recomendable especificar la versión que se desea utilizar incluyendo el número de versión en la ruta de la solicitud como https://discord.com/api/v{número_versión}. Si se omite este número en la ruta, las solicitudes se redirigirán automáticamente a la versión predeterminada actual.
Versiones de la API
10
Disponible
9
Disponible
✓ Cliente
8
Obsoleto
7
Obsoleto
6
Obsoleto
✓ API
5
Descontinuado
4
Descontinuado
3
Descontinuado
Mensajes de error
A partir de la versión 7 de la API, las respuestas a errores de formulario presentan un formato mejorado. La respuesta indicará qué clave JSON contiene el error, el código del error y un mensaje en lenguaje natural fácilmente comprensible. Discord incorpora nuevos mensajes de error con frecuencia, por lo que no resulta viable mantener una lista completa y actualizada; sin embargo, a continuación os dejamos algunos ejemplos:
{
"code": 50035,
"message": "Invalid Form Body",
"errors": {
"_errors": [
{
"code": "APPLICATION_COMMAND_TOO_LARGE",
"message": "Command exceeds maximum size (4000)"
}
]
}
}Autenticación
La autenticación con la API de Discord puede realizarse de dos formas principales:
Mediante un token de usuario o bot, obtenido tras iniciar sesión en una cuenta o registrar un bot. Para más detalles sobre la diferencia entre cuentas de usuario y bots, consulta la sección bots vs cuentas de usuario.
A través de un token bearer OAuth2 obtenido mediante la API OAuth2.
En cualquiera de los casos, la autenticación se realiza enviando el token correspondiente en la cabecera HTTP bajo el siguiente formato: Authorization: TIPO_DE_TOKEN? TOKEN
Authorization: MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWsAuthorization: Bot MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWsAuthorization: Bearer ODkxNDM2MjMzOTAzOTY0MTYx.pXvaXIpme43oSHZLXDCK7IiKA8iAjrEncriptación
Todos los servicios y protocolos a nivel HTTP (por ejemplo, HTTP, WebSocket) dentro de la API de Discord utilizan TLS 1.2.
Formato Snowflake
Discord utiliza el formato snowflake de Twitter para los identificadores únicos (IDs). Estos IDs están garantizados como únicos en todo Discord, a menos que en ciertos escenarios concretos los objetos hijo compartan el ID de su padre. Dado que los IDs Snowflake pueden ser de hasta 64 bits (ej., uint64), siempre se devuelven como cadenas en la API HTTP para evitar desbordamientos de enteros en algunos lenguajes. Consulta la documentación del Gateway para más detalles sobre la codificación.
Desglose binario de un Snowflake ID
111111111111111111111111111111111111111111 11111 11111 111111111111
64 22 17 12 0Estructura de Snowflake ID (de izquierda a derecha)
Marca de tiempo
63 a 22
42 bits
Milisegundos desde el Discord Epoch, primer segundo de 2015 o 14200704000.
(snowflake >> 22) + 1420070400000
ID interno de trabajador
21 a 17
5 bits
(snowflake & 0x3E0000) >> 17
ID interno de proceso
16 a 12
5 bits
(snowflake & 0x1F000) >> 12
Incremento
11 a 0
12 bits
Por cada ID generado en ese proceso, este número se incrementa
snowflake & 0xFFF
Convertir snowflake a fecha-hora
IDs tipo Snowflake en la paginación
Discord utiliza habitualmente los IDs tipo snowflake en muchas rutas de la API para la paginación. El paradigma de paginación estandarizado permite especificar IDs (y combinarlos con otros parámetros) para recuperar la página de resultados deseada. Para detalles concretos, consulta la documentación del endpoint correspondiente.
Es importante señalar que los IDs snowflake son simplemente números con una marca de tiempo. Por ello, si deseas paginar resultados desde el principio de los tiempos (Epoch de Discord, aunque también funciona en otros casos) o antes/después de un momento específico, puedes generar un ID snowflake correspondiente a ese instante.
Generar un ID Snowflake a partir de una marca de tiempo
(timestamp_ms - DISCORD_EPOCH) << 22Serialización de ID
Hay algunos casos en los que la API y el Gateway pueden devolver IDs en un formato inesperado. Internamente, Discord almacena los IDs como snowflakes enteros. Cuando los IDs se serializan a JSON, los bigints se transforman en cadenas. Dado que todos los IDs de Discord son snowflakes, siempre debes esperar una cadena.
Sin embargo, hay casos en los que, al enviar algo a la API, en su lugar devuelve IDs serializados como un entero; esto sucede cuando envías a la API o al Gateway un valor en un campo id que no es de tamaño bigint, por ejemplo, cuando solicitas GUILD_MEMBERS_CHUNK desde el gateway:
// Send
{
op: 8,
d: {
guild_id: [ '308994132968210433' ],
user_ids: [ '123123' ]
}
}
// Receive
{
t: 'GUILD_MEMBERS_CHUNK',
s: 3,
op: 0,
d: {
not_found: [ 123123 ],
members: [],
guild_id: '308994132968210433'
}
}Puedes ver que, en este caso, el valor de ID enviado no es un bigint; por lo tanto, cuando Discord lo serializa de vuelta a JSON, no lo transforma en una cadena. Esto nunca ocurrirá con IDs que provienen de Discord. Sin embargo, sí puede pasar si envías datos mal formateados en tus solicitudes.
Zona horaria ISO8601
Discord utiliza el formato ISO8601 para la mayoría de las fechas y horas retornadas en la API. Este formato se referencia como tipo dentro de las tablas en esta documentación.
Consistencia
Discord opera a una escala en la que la verdadera consistencia es imposible. Por esta razón, muchas operaciones dentro de la API y entre los distintos servicios de la API son eventualmente consistentes. Debido a esto, las acciones del cliente nunca pueden ser serializadas y pueden ejecutarse en cualquier orden (o incluso no ejecutarse). Bajo estas restricciones, los eventos en Discord pueden:
Nunca ser enviados a un cliente.
Ser enviados exactamente una vez al cliente.
Ser enviados hasta N veces a un mismo cliente.
Los clientes deben operar sobre los eventos y resultados recibidos de la API de manera lo más idempotente posible.
API HTTP
Agente de usuario
Los clientes que utilizan la API HTTP deben proporcionar un agente de usuario válido que especifique información sobre el cliente. Para los bots, debe contener la cadena DiscordBot. Para cuentas de usuario, consulta la sección propiedades de usuario.
Ejemplo de User Agent para bots de Discord:
User-Agent: DiscordBot ($url, $versionNumber)Los clientes pueden añadir más información y metadatos a esta cadena si lo desean.
Limitación de velocidad
La API HTTP implementa un proceso para limitar y prevenir solicitudes excesivas de acuerdo con RFC 6585. Los usuarios de la API que excedan e ignoren habitualmente los límites tendrán sus claves de API revocadas y serán bloqueados de la plataforma. Para más información sobre la limitación de solicitudes, consulta la sección de Rate Limits.
Cadenas de consulta booleanas
Ciertos endpoints en la API están documentados para aceptar booleanos en sus parámetros de cadena de consulta. Aunque no hay un sistema estándar para la representación booleana en los parámetros de la cadena de consulta, Discord representa estos casos usando True, true or 1 para verdadero y False, false o 0 para falso.
Depuración
La API HTTP acepta la cabecera opcional X-Debug-Options con una lista separada por comas de opciones de depuración. Las opciones pueden ser arbitrarias, pero las siguientes surten efecto:
canary
Fuerza el enrutamiento de la solicitud a la API canary.
trace
Fuerza el rastreo de la solicitud con APM
Todas las respuestas incluyen la cabecera X-Discord-Features con el nombre de la funcionalidad interna de la API asociada.
Rastreo APM
Discord ofrece un servicio de APM (Supervisión del Rendimiento de Aplicaciones) que permite a los empleados de Discord ver los traces (rastros) de las solicitudes realizadas a la API. Esto es útil para depurar problemas con la API, y puede activarse configurando trace en el encabezado X-Debug-Options, como se describió anteriormente.
Al rastrear solicitudes, debes proporcionar un encabezado adicional X-Client-Trace-ID con un identificador único para la solicitud. Este identificador puede generarse con el siguiente pseudocódigo:
import base64
import random
import struct
import time
class IDGenerator:
def __init__(self):
self.prefix = random.randint(0, 0xFFFFFFFF) & 0xFFFFFFFF
self.creation_time = int(time.time() * 1000)
self.sequence = 0
def generate(self, user_id: int = 0):
uuid = bytearray(24)
# Lowest signed 32 bits
struct.pack_into("<I", uuid, 0, user_id & 0xFFFFFFFF)
struct.pack_into("<I", uuid, 4, user_id >> 32)
struct.pack_into("<I", uuid, 8, self.prefix)
# Lowest signed 32 bits
struct.pack_into("<I", uuid, 12, self.creation_time & 0xFFFFFFFF)
struct.pack_into("<I", uuid, 16, self.creation_time >> 32)
struct.pack_into("<I", uuid, 20, self.sequence)
self.sequence += 1
return base64.b64encode(uuid).decode("utf-8")
if __name__ == "__main__":
generator = IDGenerator()
# Use 0 for user_id if you don't have one
generator.generate(user_id or 0)Una vez que se completa la solicitud, el trace puede visualizarse navegando a (reemplazando <trace-id> con el valor que proporcionaste).
API del Gateway
La Gateway API de Discord se utiliza para mantener conexiones WebSocket seguras, persistentes y con estado entre tu cliente y los servidores de Discord. Estas conexiones se emplean para enviar y recibir eventos en tiempo real que permiten al cliente seguir y actualizar el estado local. La Gateway API utiliza conexiones seguras WebSocket según RFC 6455. Para obtener información sobre cómo abrir conexiones Gateway, consulta la sección Gateway API.
Propiedades del cliente
Las propiedades del cliente, o super properties, contienen información de seguimiento sobre el cliente actual. Este seguimiento se utiliza para análisis y pruebas A/B. Estas propiedades se envían al identificarse con la Gateway y se incluyen en cada solicitud HTTP saliente con la cabecera X-Super-Properties, que es un objeto JSON codificado en base64.
Si estas propiedades no se proporcionan, Discord intentará extraer algunos de estos datos desde la cabecera User-Agent de la petición.
Aunque incluir esta cabecera no es obligatorio, es altamente recomendable debido a su importancia en los sistemas antiabuso. Además, muchas funciones experimentales requieren que se indique un número de compilación reciente del cliente.
Propiedades de la estructura del cliente
Debido a la naturaleza de las propiedades del cliente, la estructura de este objeto no está bien definida, y ningún campo es verdaderamente obligatorio. Además, los tipos de los campos no se verifican, y todos los enums documentados son simplemente convenciones. Los campos se marcan como obligatorios si se observa que se envían en todas las propiedades oficiales del cliente.
Android
El cliente funciona en Android.
BlackBerry
El cliente funciona en BlackBerry OS.
Mac OS X
El cliente funciona en macOS.
iOS
El cliente funciona en iOS.
Linux
El cliente funciona con Linux distribution.
Windows Mobile
El cliente funciona en Windows Mobile.
Windows
El cliente funciona en Windows.
Playstation
El cliente funciona en PlayStation.
Xbox
El cliente funciona en Xbox.
Desconocido
El cliente funciona en un dispositivo desconocido.
ID de diseño
0
CLASSIC_IA
Diseño clásico (predeterminado).
1
DESIGN_IA
Rediseño completo de móvil.
2
DESIGN_TABS_IA
El rediseño móvil con pestañas.
3
YOU_BAR_IA
El rediseño móvil con la barra de 'tú'.
Banderas de características de accesibilidad
Motores de búsqueda
DuckDuckGo
Ejemplos de propiedades de cliente
{
"os": "Windows",
"browser": "Chrome",
"device": "",
"system_locale": "en-US",
"browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
"browser_version": "136.0.0.0",
"os_version": "10",
"referrer": "https://www.reddit.com/",
"referring_domain": "www.reddit.com",
"referrer_current": "https://www.google.com/",
"referring_domain_current": "www.google.com",
"search_engine_current": "google",
"mp_keyword_current": "discord",
"release_channel": "stable",
"client_build_number": 396858,
"client_event_source": null,
"has_client_mods": false,
"client_launch_id": "9a65c85b-401d-4cf0-9c17-9676a68a482c",
"client_heartbeat_session_id": "2fc3cabd-3ca0-4716-b399-496780c302d1"
}Formato de mensajes
Discord utiliza un subconjunto de markdown para renderizar el contenido de los mensajes en sus clientes, mientras que también agrega algunas funcionalidades personalizadas para habilitar cosas como mencionar usuarios y canales. Esta funcionalidad usa los siguientes formatos:
Formatos
Usuario
<@USER_ID>
<@80351110224678912>
Usuario 1
<@!USER_ID>
<@!80351110224678912>
Canal
<#CHANNEL_ID>
<#103735883630395392>
Rol
<@&ROLE_ID>
<@&165511591545143296>
Comando de barra 2
</NAME:COMMAND_ID>
</airhorn:816437322781949972>
Emoji predeterminado
Carácteres unicode o :NAME:
💯 or :100:
Emoji personalizado
<:NAME:ID>
<:mmLol:216154654256398347>
Emoji personalizado (animado)
<a:NAME:ID>
<a:b1nzy:392938283556143104>
Marca de tiempo UNIX
<t:TIMESTAMP>
<t:1618953630>
Marca de tiempo UNIX (estilizada)
<t:TIMESTAMP:STYLE>
<t:1618953630:d>
Navegación de servidor
<id:TYPE>
<id:customize>
Correo 3
<USERNAME@DOMAIN>
<advaith@discordapp.com>
Número de teléfono 4
<+PHONE_NUMBER>
<+1 (555) 123 4567>
Usar el markdown para usuarios, roles o canales normalmente mencionará al/los destinatarios correspondientes, pero esto se puede suprimir utilizando el parámetro allowed_mentions al crear un mensaje. Los emoji estándar actualmente se renderizan usando Twemoji en escritorio/Android y los emoji nativos de Apple en iOS.
Las marcas de tiempo se expresan en segundos y muestran la marca temporal indicada en la zona horaria y el idioma del usuario.
1 Las menciones a usuarios con signo de exclamación están obsoletas y deben manejarse igual que cualquier otra mención de usuario.
2 Los subcomandos y grupos de subcomandos también se pueden mencionar usando respectivamente </NOMBRE SUBCOMANDO:ID> y </NOMBRE GRUPO_SUBCOMANDO SUBCOMANDO:ID>.
3 Puede ir opcionalmente precedido por mailto:, siguiendo el mismo formato que el esquema de URI mailto:. No se admiten varias direcciones separadas por comas. Soporta cabeceras (ejemplo: <advaith@discord.com?subject=Título&body=Contenido%20del%20mensaje>).
4 Puede ir opcionalmente precedido por tel:/sms:. Se ignoran los espacios en blanco y no es necesario el prefijo de marcación + cuando se proporciona un esquema.
Estilos de marcas de tiempo
t
16:20
Hora corta
T
16:20:30
Hora larga
d
20/04/2021
Fecha corta
D
20 April 2021
Fecha larga
f 1
20 April 2021 16:20
Fecha/Hora corta
F
Tuesday, 20 April 2021 16:20
Fecha/Hora larga
R
2 months ago
Tiempo relativo
1 Este es el predeterminado.
Tipos de navegación de servidor
Los tipos de navegación de la guild enlazan al recurso correspondiente dentro de la guild actual.
customize
Pestaña personalizada con los mensajes de incorporación del servidor.
browse
Pestaña de explorar canales.
guide
home (obsoleto)
Igual que la guía.
linked-roles
linked-roles:ROLE_ID
Conexión de rol vinculado.
Formato de CDN
Enlace base de CDN
https://cdn.discordapp.com/Discord utiliza IDs y hashes para renderizar imágenes y otros contenidos del CDN en el cliente. Estos hashes pueden recuperarse a través de diversas solicitudes a la API, como Get User. Debajo se presentan los formatos, limitaciones de tamaño y endpoints del CDN para el contenido en Discord. El formato de los archivos devueltos puede modificarse cambiando la extensión al final de la URL. Para las imágenes, el tamaño devuelto puede ajustarse añadiendo una cadena de consulta ?size=desired_size a la URL. El tamaño de la imagen puede ser cualquier potencia de dos entre 16 y 4096, con algunos valores adicionales aceptados que se detallan más abajo.
En el caso de los endpoints que admiten imágenes animadas, el hash comenzará con a_ si está disponible en formato APNG o GIF (por ejemplo: a_1269e74af4df7417b13759eae50c83dc).
Formato de archivos
JPEG
.jpg, .jpeg
PNG
.png
SVG
.svg
WebP
.webp
WebM
.webm
GIF
.gif
Lottie
.json
MP3
.mp3
MP4
.mp4
OGG
.ogg
Endpoints de CDN
1 El valor de user_index en la ruta para usuarios migrados debe ser el ID del usuario desplazado 22 bits a la derecha, módulo 6 (es decir, user_id >> 22 % 6).
El valor para usuarios no migrados es el discriminator del usuario módulo 5 (por ejemplo, Test#1337 sería 1337 % 5, lo que da 2).
El valor para equipos debe ser el ID del equipo módulo 5 (es decir, team_id % 5). Consulta la sección sobre el nuevo sistema de nombres de usuario de Discord para más información.
2 El tamaño de las imágenes devueltas es constante, y el parámetro size en la cadena de consulta es ignorado.
3 La pegatina estará disponible como PNG si su format_type es PNG o APNG, como GIF si su format_type es GIF, y como Lottie si su format_type es LOTTIE.
Las pegatinas en formato GIF no están disponibles a través del CDN y deben accederse en:
https://media.discordapp.net/stickers/{sticker_id}.gif
4 El archivo adjunto solo estará disponible en el formato en el que fue subido, el cual puede ser cualquier formato.
5 La ruta del tema solo se utiliza para obtener los recursos game_tile y logotype. Solo se admiten los temas dark y light.
6 Los nombres de recursos válidos están limitados a: img.png, static.png, asset.webm.
7 La ruta del emblema de clan es un alias de la ruta del emblema de etiqueta de servidor (guild tag badge), y existe por compatibilidad con versiones anteriores.
Icono de logro
/app-assets/{application_id}/achievements/{achievement_id}/icons/icon_hash.png
PNG, JPEG, WebP
Colección de directorio de aplicaciones
/application-directory/collection-items/{item_id}/{item_hash}.png
PNG, JPEG, WebP
Adjunto 2
/attachments/{channel_id}/[{message_id]/attachment_id}/{attachment_filename}
Formato de subida 4
Adjunto efímero 2
/ephemeral-attachments/{application_id}/{attachment_id}/{attachment_filename}
Formato de subida 4
Preset de decoración de avatar
/avatar-decoration-presets/{avatar_decoration_data_asset}.png
PNG, JPEG, WebP
Imagen de descubrimiento del servidor
/discovery-splashes/{guild_id}/{guild_discovery_splash}.png
PNG, JPEG, WebP
Encabezado de inicio del servidor
/guilds/{guild_id}/home-headers/{guild_home_header}.png
PNG, JPEG, WebP
Portada de evento programado del servidor
/guild-events/{scheduled_event_id}/{scheduled_event_cover_image}.png
PNG, JPEG, WebP
Avatar de miembro del servidor
/guilds/{guild_id}/users/{user_id}/avatars/{user_avatar}.png
PNG, JPEG, WebP, GIF
Banner de miembro del servidor
/guilds/{guild_id}/users/{user_id}/banners/{user_banner}.png
PNG, JPEG, WebP, GIF
Icono de acción de nuevo miembro del servidor
/new-member-actions/{channel_id}/{action_icon}.png
PNG, JPEG, WebP
Icono de canal de recursos del servidor
/resource-channels/{channel_id}/{channel_icon}.png
PNG, JPEG, WebP
Recurso de misión 5
/assets/quests/{quest_id}/{asset_name}, /assets/quests/{quest_id}/{theme}/{asset_name}
PNG, JPEG, GIF, SVG, WebP, WebM, MP4, M3U8, VTT, TXT
Sonido de soundboard
/soundboard-sounds/{sound_id}
MP3, OGG
Avatar archivado de usuario
/avatars/{user_id}/archived/{avatar_id}/{avatar_storage_hash}.png
PNG, JPEG, WebP, GIF
Filtro de video
/users/{user_id}/video-filter-assets/{video_filter_id}/{video_filter_asset}.png
PNG, JPEG, GIF, MP4, WEBP
Calidad de imagen
La calidad de la imagen a devolver. Solo es compatible con los formatos WebP y JPG (el resto siempre son sin pérdida). La calidad puede ser cualquiera de los siguientes valores:
lossless
La imagen se devolverá en su formato original, sin pérdida de calidad.
high
La imagen se devolverá en formato de alta calidad (por defecto).
low
La imagen se devolverá en formato de baja calidad.
Enlaces firmados de adjuntos
Los archivos adjuntos subidos al CDN de Discord (como imágenes de usuario) tienen URLs firmadas con un tiempo de caducidad predefinido. Esto incluye archivos adjuntos efímeros. Discord actualiza automáticamente las URLs de adjuntos que aparecen en el cliente, así que cuando recibas un payload con una URL firmada (por ejemplo, al hacer fetch de un mensaje), será válida.
Al pasar URLs del CDN en campos de la API, como url en un objeto de imagen de embed o avatar_url para webhooks, o incluso al enviar un mensaje, puedes pasar la URL del CDN sin parámetros adicionales y Discord la renderizará y actualizará automáticamente.
Si necesitas refrescar manualmente una URL de adjunto, puedes usar el endpoint Refresh Attachment URLs con cualquier URL.
Los demás endpoints del CDN mencionados anteriormente no están firmados, por lo que no expiran.
Parámetros de consulta de enlace adjunto
ex
Marca de tiempo en hexadecimal que indica cuándo expirará la URL del adjunto en el CDN.
is
Marca de tiempo en hexadecimal que indica cuándo se emitió la URL.
hm
Firma única que permanece válida hasta que expire la URL.
Ejemplo de enlace de archivo
https://cdn.discordapp.com/attachments/1012345678900020080/1234567891233211234/my_image.png?ex=65d903de&is=65c68ede&hm=2481f30dd67f503f54d020ae3b5533b9987fae4e55f2b4e3926e08a3fa3ee24f&CDN Data
El campo "CDN data" utiliza un esquema de URI de tipo data para representar archivos como JPG, GIF y PNG. Esto permite incrustar la imagen directamente en el valor, por ejemplo, para imágenes de perfil de usuario, usando una URI con la siguiente estructura:
data: image / jpeg;
base64, BASE64_ENCODED_JPEG_IMAGE_DATA;Es importante asegurarse de usar el tipo de contenido apropiado como image/jpeg, image/png, o image/gif, que coincida exactamente con el tipo de datos de imagen suministrada
Subida de archivos
Algunos endpoints admiten adjuntar archivos, lo cual se indica mediante el parámetro files[n]. Para añadir uno o más archivos, el cuerpo estándar application/json debe ser reemplazado por un cuerpo multipart/form-data. El cuerpo JSON del mensaje puede proporcionarse opcionalmente utilizando el parámetro payload_json.
Todos los parámetros files[n] deben incluir una subcabecera válida Content-Disposition con un filename y un parámetro name único. Cada archivo debe tener un nombre único con el formato files[n], como files, files[1] o files. El sufijo n actúa como un marcador de posición (snowflake placeholder) que puede utilizarse en el campo attachments, el cual puede pasarse al parámetro payload_json (o a los Callback Data Payloads).
Las imágenes también pueden ser referenciadas en metadatos embed usando la URL attachment://filename. El filename de estas URLs debe ser ASCII alfanumérico, con guiones bajos, guiones o puntos. A continuación se muestra un ejemplo de payload.
Edición de archivos adjuntos en mensajes
El parámetro JSON attachments incluye todos los archivos que se agregarán al mensaje, incluyendo los nuevos archivos y sus respectivos marcadores (placeholders). Al realizar una petición PATCH, solo los archivos listados en attachments se agregarán al mensaje. Todos los archivos previamente añadidos que no estén en la lista serán eliminados.
Ejemplo de cuerpos de petición (multipart/form-data)
Ten en cuenta que estos ejemplos son pequeñas secciones de una solicitud HTTP, solo para demostrar el comportamiento de este endpoint; las librerías cliente establecerán sus propios límites de formulario (boundary, que aquí solo es un ejemplo). Para más información, consulta la especificación de multipart/form-data.
Este ejemplo muestra el uso del endpoint sin payload_json.
-boundary
Content-Disposition: form-data; name="content"
Hello, World!
-boundary
Content-Disposition: form-data; name="tts"
true
-boundary--Este ejemplo demuestra el uso del endpoint con payload_json y todos los campos de contenido (content, embeds, files[n]) configurados.
-boundary
Content-Disposition: form-data; name="payload_json"
Content-Type: application/json
{
"content": "Hello, World!",
"embeds": [{
"title": "Hello, Embed!",
"description": "This is an embedded message.",
"thumbnail": {
"url": "attachment://myfile.png"
},
"image": {
"url": "attachment://mygif.gif"
}
}],
"message_reference": {
"type": 0,
"channel_id": "233648473390448640",
"message_id": "233648473390448641"
},
"attachments": [{
"id": 0,
"description": "Image of a cute little cat",
"filename": "myfile.png"
}, {
"id": 1,
"description": "Rickroll gif",
"filename": "mygif.gif"
}]
}
-boundary
Content-Disposition: form-data; name="files[0]"; filename="myfile.png"
Content-Type: image/png
[image bytes]
-boundary
Content-Disposition: form-data; name="files[1]"; filename="mygif.gif"
Content-Type: image/gif
[image bytes]
-boundary--Usar adjuntos dentro de embeds
Puedes subir archivos adjuntos al crear un mensaje y utilizar esos adjuntos dentro de tu embed. Para ello, deberás subir los archivos como parte de tu cuerpo multipart/form-data. Asegúrate de subir archivos que contengan un nombre de archivo (filename), ya que será necesario referenciarlo en tu payload. Ten en cuenta que Discord normaliza los nombres de archivo, por lo que enviar caracteres exóticos en el nombre podría producir resultados inesperados.
Solo se permiten archivos con extensión .jpg, .jpeg, .png, .webp y .gif por el momento. Otros tipos de archivos no son compatibles.
Dentro de un objeto embed, puedes establecer una imagen para que utilice un adjunto como su URL, utilizando la siguiente sintaxis de esquema de adjunto:
attachment://filename.png
Por ejemplo:
{
"embeds": [
{
"image": {
"url": "attachment://screenshot.png"
}
}
]
}Subida a Google Cloud
Puedes subir archivos adjuntos grandes rápidamente y de forma directa al bucket de almacenamiento de Google Cloud de Discord, utilizando el endpoint de crear archivos para generar enlaces de subida, y enviando a cada enlace generado una solicitud PUT con el adjunto como cuerpo.
Esto te permite evitar el límite de tamaño de solicitud de Discord de 200 MiB y subir archivos de hasta 500 MiB directamente a Google Cloud. Ten en cuenta que los límites de tamaño de archivo seguirán aplicando al enviar el adjunto en un mensaje.
Un ejemplo de implementación en pseudocódigo Python sería:
import requests
import os
url = "https://discord.com/api/v10/channels/<channel_id>/attachments"
headers = {
"Authorization": "Bot <bot_token>"
}
filename = "cat.png"
size = os.stat(filename).st_size
json = {
"files": [{
"file_size": size,
"filename": filename
}]
}
r = requests.post(url, headers=headers, json=json)
r.raise_for_status()
upload = r.json()['attachments'][0]
with open(filename, "r") as f:
data = f.read()
r = requests.put(upload['upload_url'], data=data)
r.raise_for_status()
upload_filename = upload['upload_filename']Ahora, en vez de enviar el archivo adjunto nuevamente en el cuerpo del formulario dentro de la solicitud, ¡puedes simplemente enviar el upload_filename! Por ejemplo:
{
"content": "look at my cute cat!",
"attachments": [
{
"id": "0",
"filename": "cat.png",
"uploaded_filename": "6a08e58a-265f-485a-8c85-5cd4df0edde0/cat.png"
}
]
}Locales
ar
Árabe
العربية
bg
Búlgaro
български
cs
Checo
Čeština
da
Danés
Dansk
de
Alemán
Deutsch
el
Griego
Ελληνικά
en-GB
Inglés, Reino Unido
English, UK
en-US
Inglés, Estados Unidos
English, US
es-ES
Español
Español
es-419
Español, LATAM
Español de América Latina
fi
Finés
Suomi
fr
Francés
Français
hi
Hindi
हिन्दी
hr
Croata
Hrvatski
hu
Húngaro
Magyar
id
Indonés
Bahasa Indonesia
it
Italiano
Italiano
ja
Japonés
日本語
ko
Coreano
한국어
lt
Lituano
Lietuviškai
nl
Neerlandés
Nederlands
no
Noruego
Norsk
pl
Polaco
Polski
pt-BR
Portugués, Brasil
Português do Brasil
ro
Rumano
Română
ru
Ruso
Pусский
sv-SE
Sueco
Svenska
th
Tailandés
ไทย
tr
Turco
Türkçe
uk
Ucraniano
Українська
vi
Vietnamita
Tiếng Việt
zh-CN
Chino, China
中文
zh-TW
Chino, Taiwán
繁體中文
Claro, aquí tienes la traducción profesional al español del fragmento completo, respetando el formato y terminología técnica:
Referencia de documentación
Esta documentación utiliza varias convenciones para describir la API. A continuación se presentan algunas convenciones comunes que puedes encontrar:
Campos de recursos nulos y opcionales
Los campos de recurso que pueden contener un valor null tienen tipos que se indican con un signo de interrogación como prefijo. Los campos que son opcionales tienen nombres que se indican con un signo de interrogación como sufijo.
Ejemplo de campos nulos y opcionales
¹ Puede ser inesperadamente null a las 3:00 AM de los martes para cuentas creadas el 23 de junio de 2017.
optional_field?¹
string
nullable_field
?string
optional_and_nullable_field?
?string
Límites de los campos
Se hace un esfuerzo razonable por documentar los límites de los campos cuando sea posible (por ejemplo, la longitud máxima de una cadena, el número máximo de elementos en un array). Estos límites no son exhaustivos y pueden no cubrir todos los casos extremos.
Se utiliza un límite por defecto de 1521 elementos en arrays y 152133 caracteres cuando no existe un límite bien definido.
Campos obsoletos/eliminados
Los campos obsoletos se marcarán con un aviso (obsoleto) junto a ellos. Los campos eliminados (que se mantienen por motivos de completitud, como en los enums) se marcarán con tachado.
Campos de eventos
Ciertos campos solo están presentes en estructuras recibidas a través del Gateway. Estos campos normalmente se documentan en la sección del Gateway en lugar de en la estructura principal.
Insignias
Algunos endpoints pueden tener insignias que describen comportamientos adicionales en forma resumida. A continuación algunos ejemplos:
MFA requerida
Este endpoint puede requerir que los usuarios con autenticación multifactor habilitada se autentiquen para ciertas acciones. Consulta la documentación de verificación MFA para la implementación.
Esto no aplica a solicitudes mediante OAuth2 ni a bots.
Motivo del registro en el log de auditoría
El endpoint puede utilizarse con una cabecera X-Audit-Log-Reason. Esta cabecera se usa para proporcionar un motivo para la acción que se está realizando. Ese motivo se mostrará en la entrada del registro de auditoría correspondiente. Consulta la documentación del log de auditoría para más información.
Solicitud no autenticada
Estas solicitudes no requieren que la cabecera Authorization esté presente.
Solicitud OAuth2
El endpoint puede usarse con un bearer token en la cabecera Authorization. El scope específico requerido (si lo hay) se mostrará al pasar el cursor sobre la insignia.
Endpoint obsoleto
Este endpoint sigue activo y funcionalmente igual, pero se recomienda evitarlo en lo posible, ya que podría eliminarse en una futura versión de la API.