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

# Messages API — Send and Retrieve Conversation Messages

> REST API endpoints to list messages in a conversation and send new messages including text, attachments, and WhatsApp template messages.

The Messages API lets you retrieve message history from a conversation and send new messages programmatically. Use it to build chatbots, send automated follow-ups, or read conversation transcripts.

## List messages in a conversation

Retrieve all messages in a conversation, ordered oldest to newest.

```
GET /conversations/{conversation_id}/messages
```

### Path parameters

<ParamField path="conversation_id" type="string" required>
  The ID of the conversation.
</ParamField>

### Query parameters

<ParamField query="page" type="integer">
  Page number. Default: `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  Messages per page. Default: `50`. Max: `100`.
</ParamField>

### Example request

```bash theme={null}
curl "https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P/messages" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json theme={null}
{
  "data": [
    {
      "id": "msg_01HX5E2N6P8R0S",
      "type": "incoming",
      "content": "Halo, saya ingin tanya tentang harga produk X",
      "sender": {
        "type": "contact",
        "id": "ct_01HX3C0L4N6P8Q",
        "name": "Budi Santoso"
      },
      "attachments": [],
      "created_at": "2024-03-15T08:30:00Z"
    },
    {
      "id": "msg_01HX5F3O7Q9S1T",
      "type": "outgoing",
      "content": "Halo Budi! Untuk harga produk X, saat ini adalah Rp 150.000 per unit.",
      "sender": {
        "type": "agent",
        "id": "usr_01HX0Z7I1K3L5M",
        "name": "Sari Dewi"
      },
      "attachments": [],
      "created_at": "2024-03-15T08:35:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}
```

### Message fields

<ResponseField name="id" type="string">
  Unique message ID.
</ResponseField>

<ResponseField name="type" type="string">
  `incoming` (from customer) or `outgoing` (from agent/bot) or `activity` (system event).
</ResponseField>

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

<ResponseField name="sender" type="object">
  Who sent the message. Includes `type` (`contact`, `agent`, or `bot`), `id`, and `name`.
</ResponseField>

<ResponseField name="attachments" type="array">
  List of attached files. Each attachment has `url`, `content_type`, and `file_name`.
</ResponseField>

## Send a message

Send a new message in a conversation. The message is delivered through the conversation's channel.

```
POST /conversations/{conversation_id}/messages
```

### Path parameters

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

### Request body

<ParamField body="content" type="string">
  Text content of the message. Required unless sending a template message.
</ParamField>

<ParamField body="template_id" type="string">
  ID of a WhatsApp Message Template to send. Use for outbound WhatsApp messages to customers who haven't messaged in the last 24 hours.
</ParamField>

<ParamField body="template_variables" type="object">
  Key-value pairs for template variable substitution (e.g., `{"name": "Budi", "order_id": "12345"}`).
</ParamField>

<ParamField body="private" type="boolean">
  Set to `true` to send as an internal note (not visible to the customer). Default: `false`.
</ParamField>

### Example: send a text message

```bash theme={null}
curl -X POST \
  https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Terima kasih telah menghubungi kami. Pesanan Anda sudah kami proses."
  }'
```

### Example: send a WhatsApp template message

```bash theme={null}
curl -X POST \
  https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_order_confirmation",
    "template_variables": {
      "customer_name": "Budi",
      "order_id": "ORD-12345",
      "total": "Rp 450.000"
    }
  }'
```

<Note>Template messages require a pre-approved WhatsApp Message Template. Create and submit templates for approval in your Meta Business Manager account.</Note>