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

# Send a message

`POST /v1/messages`

## Request

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

Send a message into a lead’s existing LinkedIn conversation. If Botdog has not recorded the conversation yet (for example the lead connected and wrote first), it is found on LinkedIn and recorded, and its id is returned as `chatId`. Never starts a new conversation. Rate-limited per sending account.

## Request body

- SendMessageDto
  - `leadId` string, required: The lead to message (must already have a conversation)
  - `text` string, required: The message text

## Response `200`

- SendMessageResponseDto
  - `leadId` string: The lead that was messaged
  - `chatId` string, required: The conversation the message was sent to. Use it with POST /v1/conversations/{id}/reply.
  - `messageId` string, nullable, required: The provider message id, if returned

## Other responses

- `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 with this lead yet
- `429`: Per-account send 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)