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

# Messages

> Send outbound iMessage text and media bubbles, and fetch conversation message history.

Send outbound blue bubbles to Apple devices via active conversation sessions or direct phone numbers, and retrieve chronological message logs.

### Body Parameters

<ParamField body="conversation_id" type="string">
  Active conversation session ID (e.g. `conv_01J8ABC123XYZ`). Required if `to` is not provided.
</ParamField>

<ParamField body="to" type="string">
  Recipient phone number in E.164 format (e.g. `+15551234567`). Required if `conversation_id` is not provided.
</ParamField>

<ParamField body="text" type="string" required>
  The message text body to transmit.
</ParamField>

<ParamField body="media_url" type="string">
  Optional URL to a media attachment (PNG, JPEG, GIF, PDF) delivered inline with the message.
</ParamField>

<ParamField body="identity_id" type="string">
  Optional agent identity ID or handle initiating the message.
</ParamField>

### Response Fields

<ResponseField name="id" type="string">
  Unique message identifier (e.g. `imsg_01J8DEF456GHI`).
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The associated conversation session ID.
</ResponseField>

<ResponseField name="direction" type="string">
  Message direction: `outbound`.
</ResponseField>

<ResponseField name="status" type="string">
  Delivery state: `sent`, `queued`, or `failed`.
</ResponseField>

<ResponseField name="sent_at" type="string">
  ISO 8601 transmission timestamp.
</ResponseField>

***

## Listing Conversation Messages

Retrieve chronological message history for an active or archived conversation:

```http theme={null}
GET https://api.wirebox.sh/api/v1/imessage/messages?conversation_id={conversation_id}&limit=50
```

<RequestExample>
  ```bash cURL theme={null}
  # 1. Send outbound iMessage
  curl -X POST https://api.wirebox.sh/api/v1/imessage/messages \
    -H "Authorization: Bearer $WIREBOX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15551234567",
      "text": "Hello! Your background job finished successfully."
    }'

  # 2. List conversation messages
  curl -X GET "https://api.wirebox.sh/api/v1/imessage/messages?conversation_id=conv_01J8ABC123XYZ&limit=20" \
    -H "Authorization: Bearer $WIREBOX_API_KEY"
  ```

  ```python Python theme={null}
  from wirebox import Wirebox

  with Wirebox() as wb:
      # 1. Send outbound iMessage
      res = wb.imessage.messages.send(
          to="+15551234567",
          text="Hello! Your background job finished successfully."
      )
      print("Sent message:", res.id)

      # 2. List message history
      history = wb.imessage.messages.list(conversation_id="conv_01J8ABC123XYZ", limit=20)
      for m in history.messages:
          print(f"[{m.direction}] {m.sender}: {m.text}")
  ```

  ```ts TypeScript theme={null}
  import { Wirebox } from "@wirebox-sh/sdk";

  const wb = new Wirebox();

  // 1. Send outbound iMessage
  const res = await wb.imessage.messages.send({
    to: "+15551234567",
    text: "Hello! Your background job finished successfully.",
  });
  console.log("Sent message:", res.id);

  // 2. List message history
  const history = await wb.imessage.messages.list({
    conversation_id: "conv_01J8ABC123XYZ",
    limit: 20,
  });
  for (const m of history.messages) {
    console.log(`[${m.direction}] ${m.sender}: ${m.text}`);
  }
  ```

  ```bash CLI theme={null}
  # Send outbound iMessage
  wirebox imessage send --to +15551234567 --text "Hello! Your background job finished successfully."

  # List conversation messages
  wirebox imessage messages conv_01J8ABC123XYZ --limit 20
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK (Send Message) theme={null}
  {
    "id": "imsg_01J8DEF456GHI",
    "conversation_id": "conv_01J8ABC123XYZ",
    "direction": "outbound",
    "status": "sent",
    "text": "Hello! Your background job finished successfully.",
    "sent_at": "2026-09-17T10:30:00Z"
  }
  ```

  ```json 200 OK (List Messages) theme={null}
  {
    "messages": [
      {
        "id": "imsg_01J8DEF456GHI",
        "conversation_id": "conv_01J8ABC123XYZ",
        "direction": "inbound",
        "sender": "+15551234567",
        "text": "Can you check on my database migration?",
        "media_url": null,
        "created_at": "2026-09-17T10:29:15Z"
      },
      {
        "id": "imsg_01J8DEF456GHJ",
        "conversation_id": "conv_01J8ABC123XYZ",
        "direction": "outbound",
        "sender": "eva",
        "text": "Hello! Your background job finished successfully.",
        "media_url": null,
        "created_at": "2026-09-17T10:30:00Z"
      }
    ],
    "next_cursor": null
  }
  ```
</ResponseExample>