> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingback.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Message

> Send an agent reply in a conversation.

## Overview

Sends a message from the authenticated agent into a conversation. The message is delivered to the customer via the conversation's channel adapter (e.g. live chat widget, WhatsApp, email). SLA first-response time is recorded on the first agent message.

<Note>
  Your plan's monthly message limit applies. If you exceed your plan's `max_messages_per_month`, this endpoint returns an error. Upgrade your plan to increase the limit.
</Note>

## Request

**Method**: `POST`
**URL**: `/api/v1/conversations/{conversation_id}/messages`

### Headers

| Header        | Value            |
| ------------- | ---------------- |
| Authorization | Bearer {token}   |
| Content-Type  | application/json |

### Path parameters

<ParamField path="conversation_id" type="string (UUID)" required>
  The UUID of the conversation to send a message in.
</ParamField>

### Body parameters

<ParamField body="content" type="string" required>
  The text content of the message.
</ParamField>

<ParamField body="attachments" type="array">
  Optional list of attachment objects. Upload files first using `POST /api/v1/conversations/{conversation_id}/upload` to obtain URLs, then reference them here. Defaults to an empty array.
</ParamField>

## Response

Returns the created message object.

<ResponseField name="id" type="string (UUID)">
  Unique identifier for the message.
</ResponseField>

<ResponseField name="conversation_id" type="string (UUID)">
  The conversation this message belongs to.
</ResponseField>

<ResponseField name="sender_type" type="string">
  Always `"agent"` for messages sent via this endpoint.
</ResponseField>

<ResponseField name="sender_id" type="string (UUID) | null">
  UUID of the authenticated agent who sent the message.
</ResponseField>

<ResponseField name="content" type="string">
  The text content of the message.
</ResponseField>

<ResponseField name="attachments" type="array">
  List of attachment objects included with the message.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Timestamp when the message was sent.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.pingback.live/api/v1/conversations/c3d4e5f6-a7b8-9012-cdef-123456789012/messages \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "content": "Thanks for reaching out! I can help you with that.",
      "attachments": []
    }'
  ```

  ```javascript JavaScript theme={null}
  const conversationId = 'c3d4e5f6-a7b8-9012-cdef-123456789012';
  const response = await fetch(
    `https://api.pingback.live/api/v1/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        content: 'Thanks for reaching out! I can help you with that.',
        attachments: [],
      }),
    }
  );
  const message = await response.json();
  ```
</CodeGroup>

### Response example

```json theme={null}
{
  "id": "g7b8c9d0-e1f2-3456-abcd-567890123456",
  "conversation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "sender_type": "agent",
  "sender_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "Thanks for reaching out! I can help you with that.",
  "attachments": [],
  "created_at": "2024-03-01T09:05:00Z"
}
```

## Errors

| Status | Meaning                                                    |
| ------ | ---------------------------------------------------------- |
| 401    | Unauthorized — missing or invalid Bearer token             |
| 403    | Plan message limit reached for this month                  |
| 404    | Conversation not found or does not belong to your business |
| 422    | Validation error — `content` is required                   |