# Start (/api/events/giveaways/start)



## Event Type [#event-type]

```ts
"giveaway.start"
```

## Description [#description]

This event is triggered whenever a giveaway is created, whether it was started from the bot, from the dashboard, or by an automation.

## Payload Structure [#payload-structure]

<TypeTable
  type="{
  giveawayId: {
    description: 'Unique identifier for the giveaway',
    type: 'string',
  },
  prize: {
    description: 'The prize as it is written on the giveaway message',
    type: 'string',
  },
  description: {
    description: 'Description shown under the prize, empty when there is none',
    type: 'string',
  },
  channelId: {
    description: 'Discord channel the giveaway was posted in',
    type: 'string',
  },
  messageId: {
    description: 'Discord message ID of the giveaway message',
    type: 'string',
  },
  messageUrl: {
    description: 'Direct link to the giveaway message',
    type: 'string',
  },
  winnersCount: {
    description: 'How many winners will be drawn',
    type: 'number',
  },
  creatorId: {
    description: 'Discord user ID of who created the giveaway',
    type: 'string',
  },
  hostedBy: {
    description: 'Discord user ID of the host, which is the creator unless another host was set',
    type: 'string',
  },
  createdAt: {
    description: 'ISO 8601 timestamp when the giveaway was created',
    type: 'string',
  },
  duration: {
    description: 'The end condition. endsAt is only present for time based giveaways',
    type: '{ type: &#x22;DURATION&#x22; | &#x22;PARTICIPANTS&#x22; | &#x22;MEMBERS&#x22;; value: number; endsAt?: string; }',
  },
  requiredRoles: {
    description: 'Role IDs a member needs to enter, empty when there are none',
    type: 'string[]',
  },
  requiredRolesMode: {
    description: 'Whether a member needs any of the required roles or all of them',
    type: '&#x22;OR&#x22; | &#x22;AND&#x22;',
  },
  blockedRoles: {
    description: 'Role IDs that may not enter',
    type: 'string[]',
  },
  bypassRoles: {
    description: 'Role IDs that skip every entry requirement',
    type: 'string[]',
  },
  winnerRoles: {
    description: 'Role IDs handed to the winners when the giveaway ends',
    type: 'string[]',
  },
}"
/>

<Callout type="info">
  `duration.value` means a different thing per type: milliseconds for `DURATION`, a participant goal for `PARTICIPANTS`, and a server member goal for `MEMBERS`. Only a `DURATION` giveaway has a known end time, so `endsAt` is left out of the other two.
</Callout>

## Example Payload [#example-payload]

```json
{
  "type": "giveaway.start",
  "payload": {
    "giveawayId": "hT7pLm2Qa9",
    "prize": "Nitro Classic",
    "description": "",
    "channelId": "1140972530400776294",
    "messageId": "1141002938471829504",
    "messageUrl": "https://discord.com/channels/1140972530400776290/1140972530400776294/1141002938471829504",
    "winnersCount": 3,
    "creatorId": "280158289667555328",
    "hostedBy": "280158289667555328",
    "createdAt": "2024-01-18T15:30:00.000Z",
    "duration": {
      "type": "DURATION",
      "value": 86400000,
      "endsAt": "2024-01-19T15:30:00.000Z"
    },
    "requiredRoles": ["1140972530400776291"],
    "requiredRolesMode": "OR",
    "blockedRoles": [],
    "bypassRoles": [],
    "winnerRoles": []
  }
}
```

## Example Usage [#example-usage]

```ts
app.post('/webhook', (req, res) => {
  const { type, payload } = req.body;

  if (type === 'giveaway.start') {
    console.log(`Giveaway started: ${payload.prize}`);
    console.log(`Winners: ${payload.winnersCount}`);

    // Mirror the giveaway on your own site
    await createGiveaway({
      id: payload.giveawayId,
      prize: payload.prize,
      url: payload.messageUrl,
      endsAt: payload.duration.endsAt,
    });
  }

  res.status(200).send('OK');
});
```

## Use Cases [#use-cases]

* Announce new giveaways on your website, forum, or another platform
* Keep an external record of every giveaway a server has run
* Schedule your own reminder before a time based giveaway ends
* Audit who is starting giveaways and with what requirements