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

# Get Message

> Retrieve details of a specific SMS message

Get detailed information about a message, including its delivery status.

## Request Body

<ParamField body="message_id" type="string" required>
  The unique identifier of the message to retrieve.
</ParamField>

## Response

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

<ResponseField name="contact_id" type="string">
  Associated contact identifier, or `null`.
</ResponseField>

<ResponseField name="thread_id" type="string">
  Stable identifier for the conversation this message belongs to. Deterministic — every inbound and outbound message between the same contact and service number shares the same `thread_id`, regardless of direction or phone-number formatting. Use it to group messages into threads.
</ResponseField>

<ResponseField name="from_number" type="string">
  The sending phone number.
</ResponseField>

<ResponseField name="to_number" type="string">
  The recipient phone number.
</ResponseField>

<ResponseField name="body" type="string">
  The message content.
</ResponseField>

<ResponseField name="direction" type="string">
  Either `inbound` or `outbound`.
</ResponseField>

<ResponseField name="status" type="string">
  Message status: `pending`, `sent`, `delivered`, `undelivered`, or `failed`.
</ResponseField>

<ResponseField name="is_ai_generated" type="boolean">
  Whether this message was generated by the AI agent.
</ResponseField>

<ResponseField name="sent_at" type="string">
  ISO 8601 timestamp when the message was sent.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the message was created.
</ResponseField>

<ResponseField name="message_sid" type="string">
  Carrier message SID for tracking, or `null`.
</ResponseField>

<ResponseField name="delivered_at" type="string">
  ISO 8601 timestamp when delivery was confirmed, or `null`.
</ResponseField>

<ResponseField name="sentiment" type="string">
  Detected sentiment: `positive`, `neutral`, `negative`, or `null`.
</ResponseField>

<ResponseField name="agent_id" type="string">
  Agent that generated the message, or `null`.
</ResponseField>

<ResponseField name="translation" type="string">
  Translated message content, or `null`.
</ResponseField>

<ResponseField name="media" type="array">
  Attachments on the message (inbound WhatsApp photos, voice notes, video, documents). Empty array when there are none. Each URL is freshly signed on every request and valid for 24 hours — re-fetch the message to get a new link rather than persisting the URL.

  <Expandable title="media item properties">
    <ResponseField name="url" type="string">
      Time-limited (24h) signed download URL for the binary. No credentials required to GET it.
    </ResponseField>

    <ResponseField name="mime_type" type="string">
      The content type, e.g. `image/jpeg`, `audio/ogg`, `application/pdf`.
    </ResponseField>

    <ResponseField name="kind" type="string">
      Coarse category derived from `mime_type`: `photo`, `audio`, `video`, or `file`.
    </ResponseField>

    <ResponseField name="caption" type="string">
      Caption the sender attached to the media, or `null`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="delivery_error" type="object">
  Present (non-`null`) only when `status` is `failed` or `undelivered`. Explains why the provider rejected delivery — works for both WhatsApp (Meta) and SMS (SignalWire).

  <Expandable title="delivery_error properties">
    <ResponseField name="code" type="string">
      Provider error code — the Meta error code for WhatsApp (e.g. `131042`) or the SignalWire error code for SMS (e.g. `30003`).
    </ResponseField>

    <ResponseField name="reason" type="string">
      Human-readable failure reason from the provider (e.g. `Business eligibility payment issue`).
    </ResponseField>

    <ResponseField name="at" type="string">
      ISO 8601 timestamp of the provider's failure callback.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.magpipe.ai/functions/v1/get-message \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"message_id": "8e4f9a00-c3d4-6e5f-1a2b-890123cdef01"}'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.magpipe.ai/functions/v1/get-message',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message_id: '8e4f9a00-c3d4-6e5f-1a2b-890123cdef01'
      }),
    }
  );

  const message = await response.json();
  console.log('Status:', message.status);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.magpipe.ai/functions/v1/get-message',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={'message_id': '8e4f9a00-c3d4-6e5f-1a2b-890123cdef01'}
  )

  message = response.json()
  print(f"Status: {message['status']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "8e4f9a00-c3d4-6e5f-1a2b-890123cdef01",
    "contact_id": "3a1b2c00-d4e5-6f7a-8b9c-012345abcdef",
    "thread_id": "a17b4735-15d2-5274-9460-74f8554172cb",
    "from_number": "+16045551234",
    "to_number": "+14155551234",
    "body": "Your appointment is confirmed for tomorrow at 2pm.",
    "direction": "outbound",
    "status": "delivered",
    "is_ai_generated": false,
    "sent_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "message_sid": "SM1234567890abcdef",
    "delivered_at": "2024-01-15T10:30:02Z",
    "sentiment": null,
    "agent_id": null,
    "translation": null,
    "media": [],
    "delivery_error": null
  }
  ```

  ```json Inbound with Media (WhatsApp voice note) theme={null}
  {
    "id": "b40266e5-da45-4a86-9793-e256e231bf77",
    "contact_id": null,
    "thread_id": "a17b4735-15d2-5274-9460-74f8554172cb",
    "from_number": "17789984118",
    "to_number": "1059545750567735",
    "body": "Scheduling Paul from Lonsdale Electric next week to review the plans.",
    "direction": "inbound",
    "status": "delivered",
    "is_ai_generated": false,
    "sent_at": "2026-06-16T17:16:09Z",
    "created_at": "2026-06-16T17:16:17Z",
    "message_sid": null,
    "delivered_at": null,
    "sentiment": null,
    "agent_id": "2af715f7-c995-4fd5-9f2b-bdb28d5a8c3a",
    "translation": null,
    "media": [
      {
        "url": "https://<project>.supabase.co/storage/v1/object/sign/whatsapp-media/inbound/...",
        "mime_type": "audio/ogg",
        "kind": "audio",
        "caption": null
      }
    ],
    "delivery_error": null
  }
  ```

  ```json Failed Delivery (WhatsApp) theme={null}
  {
    "id": "8d626ef9-575f-4497-a725-01f91adbcd8e",
    "thread_id": "c91a7e02-4f8b-5d6c-8e0a-1b2c3d4e5f60",
    "from_number": "1059545750567735",
    "to_number": "+16045628647",
    "body": "Hi {{1}}, time for your daily site report.",
    "direction": "outbound",
    "status": "failed",
    "is_ai_generated": false,
    "sent_at": "2026-06-10T18:30:18Z",
    "created_at": "2026-06-10T18:30:18Z",
    "message_sid": null,
    "delivered_at": null,
    "sentiment": null,
    "agent_id": "2af715f7-c995-4fd5-9f2b-bdb28d5a8c3a",
    "translation": null,
    "media": [],
    "delivery_error": {
      "code": "131042",
      "reason": "Business eligibility payment issue",
      "at": "2026-06-10T18:30:26Z"
    }
  }
  ```
</ResponseExample>