---
title: "Schedule a message"
method: POST
path: "/v1/messages/schedule"
tags: ["messaging"]
---

# Schedule a message

`POST /v1/messages/schedule`

## Request

- Base URL: `https://api.botdog.co`
- URL: `https://api.botdog.co/v1/messages/schedule`
- Auth: API key in header `x-api-key`

Schedule a message to a lead’s conversation for a future time (60s–90 days). Counts against the daily per-account budget.

## Request body

- ScheduleMessageDto
  - `leadId` string, required: The lead to message (must already have a conversation)
  - `text` string, required: The message text
  - `fireAt` string, required: When to send (ISO 8601). Must be 60s–90 days in the future. Counts against the daily per-account send budget.

## Response `201`

- ScheduledMessageResponseDto
  - `scheduledMessageId` string, required: The scheduled message id
  - `chatId` string, required: The conversation it will be sent to
  - `fireAt` string, date-time, required: When it will fire
  - `status` string, required: The status

## Other responses

- `400`: fireAt out of range
- `401`: Unauthorized. API key is missing or invalid.
- `403`: The key owner has no seat assigned (write endpoints only), the team is on Botdog Managed and so may only read (write endpoints only), or the subscription/plan does not permit this.
- `404`: Lead not found
- `422`: No conversation exists yet
- `429`: Per-account daily limit reached

---

[API](https://skmtc.dev/botdog/apis/botdog-api.md) · [All operations](https://skmtc.dev/botdog/apis/botdog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/botdog/apis/botdog-api/revisions/6c0213d8a608?raw)