---
updatedAt: 2026-08-06T09:23:36.000Z
agentTools:
  projectIndex: https://developers.alcmeon.com/llms.txt
---

# List messages

Return up to 10 messages for the specified conversation, ordered by increasing message id. Paging can be performed by using the `min_message_id` parameter, initialized to zero and updated after each successful call to the max of the returned message ids + 1.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "servers": [
    {
      "url": "https://inmessage.alcmeon.com/prod/api"
    }
  ],
  "info": {
    "title": "InMessage",
    "version": "1.0"
  },
  "x-readme": {
    "explorer-enabled": false
  },
  "components": {
    "parameters": {
      "page_id": {
        "in": "path",
        "name": "page_id",
        "schema": {
          "type": "string"
        },
        "required": true,
        "description": "ID of the page. This is not an integer."
      }
    },
    "schemas": {
      "RateLimitResponseError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Rate limit reached"
          },
          "details": {
            "type": "string",
            "description": "A string showing the time when the rate limit will be reset. Example: {'rate_limited_until': '2024-01-22T13:05:41Z'}\n"
          }
        }
      },
      "Button": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "label of button, displayed on screen"
          },
          "payload": {
            "type": "string",
            "description": "arbitrary string hidden from the user, associated with button"
          }
        }
      },
      "User": {
        "description": "The sender or recipient of a message. If message.is_from_brand == false then authenticated is null.\n",
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "a unique id associated with the user"
          },
          "name": {
            "type": "string",
            "description": "a human-readable name associated with the user"
          },
          "authenticated": {
            "$ref": "#/components/schemas/Authenticated"
          }
        }
      },
      "Authenticated": {
        "type": "object",
        "properties": {
          "customer_id": {
            "type": "string",
            "description": "a stage unique id for the customer."
          },
          "sms_notification_phone_number": {
            "type": "string",
            "description": "If specified, the phone number to send SMS notifications to when an agent sends a reply in Alcméon.\n"
          },
          "notification_id": {
            "type": "string",
            "description": "If specified, the notification id to use in the associated [webhook](#post-/notify)\n"
          },
          "attributes": {
            "description": "the list of attributes to display to customer support agents in the Alcméon console.\n",
            "type": "array",
            "items": {
              "description": "a pair of key/value items to display on screen",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "MessageBase": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "unique id for message"
          },
          "is_from_brand": {
            "type": "boolean",
            "description": "true if message was sent by brand"
          },
          "datetime": {
            "type": "string"
          },
          "from_user": {
            "$ref": "#/components/schemas/User"
          },
          "to_user": {
            "$ref": "#/components/schemas/User"
          },
          "disable_input": {
            "type": "boolean",
            "description": "If true, input is disabled.  This field can be set to true only when `is_from_brand` is true too.\n"
          }
        }
      },
      "Start": {
        "description": "Start data. (Optional)\n",
        "type": "object",
        "properties": {
          "ref": {
            "type": "string",
            "description": "Optional. Ref value of a \"Link with ref\" scenario box. This is used to start conversation from a specific entry box.\n"
          }
        }
      },
      "StartMessagePayload": {
        "description": "This is the equivalent of a `Get Started` button on Messenger. i.e., the expectation is that this is triggered only upon a user interaction with a button that clearly indicates an intent to start a conversation with the brand.\n\nThis payload should also be triggered upon a click on a `RESTART` button from the persistent menu.\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "start-conversation"
            ]
          },
          "start-conversation": {
            "$ref": "#/components/schemas/Start"
          }
        }
      },
      "StartMessage": {
        "description": "When `type = start-conversation`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/StartMessagePayload"
          }
        ]
      },
      "Postback": {
        "description": "Postback data.\n",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "The label of the button displayed to the user\n"
          },
          "payload": {
            "type": "string",
            "description": "The payload associated with the postback button displayed to the user\n"
          }
        }
      },
      "PostbackMessage": {
        "description": "When `type = postback`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/PostbackMessagePayload"
          }
        ]
      },
      "PostbackMessagePayload": {
        "description": "The user clicked on a `postback` item from the persistent menu.\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "postback"
            ]
          },
          "postback": {
            "$ref": "#/components/schemas/Postback"
          }
        }
      },
      "Text": {
        "description": "The text object",
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "text to send to the user"
          }
        }
      },
      "TextMessage": {
        "description": "When `type = text`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/TextMessagePayload"
          },
          {
            "type": "object",
            "properties": {
              "text": {
                "type": "object",
                "properties": {
                  "buttons": {
                    "description": "The list of buttons permanently displayed with the text",
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "description": "The type of the button. For now, only url buttons are supported. They will be rendered as a clickable link",
                          "type": "string",
                          "enum": [
                            "url_button"
                          ]
                        },
                        "url_button": {
                          "type": "object",
                          "properties": {
                            "title": {
                              "description": "The label displayed on the button",
                              "type": "string"
                            },
                            "web_url": {
                              "description": "The url which should be opened upon a click on this button",
                              "type": "string",
                              "format": "uri"
                            },
                            "open_link_in_new_tab": {
                              "description": "Should the url associated with this button be opened in a new tab or not ?",
                              "type": "boolean"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              },
              "buttons": {
                "description": "If specified, the list of buttons to display below the text",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Button"
                }
              }
            }
          }
        ]
      },
      "TextMessagePayload": {
        "description": "The user typed something in the text input field\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text"
            ]
          },
          "text": {
            "$ref": "#/components/schemas/Text"
          }
        }
      },
      "ButtonMessage": {
        "description": "When `type = button`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/ButtonMessagePayload"
          }
        ]
      },
      "ButtonMessagePayload": {
        "description": "The user clicked on a button\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "button"
            ]
          },
          "button": {
            "$ref": "#/components/schemas/Button"
          }
        }
      },
      "CarouselMessage": {
        "description": "When `type = carousel`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/CarouselMessagePayload"
          }
        ]
      },
      "CarouselMessagePayload": {
        "description": "A carousel message",
        "type": "object",
        "required": [
          "type",
          "slides"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "carousel"
            ]
          },
          "slides": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CarouselSlide"
            },
            "description": "A list of slides in the carousel"
          }
        }
      },
      "CarouselSlide": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "The main text of the slide"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Additional description text for the slide (optional)"
          },
          "media_uuid": {
            "type": "string",
            "nullable": true,
            "description": "The UUID of the media for this slide (optional)"
          },
          "buttons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CarouselButton"
            },
            "description": "A list of buttons for the slide"
          }
        }
      },
      "CarouselButton": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The text label for the button"
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "A URL to open when the button is clicked (optional)"
          },
          "payload": {
            "type": "string",
            "nullable": true,
            "description": "A payload to send when the button is clicked (optional)"
          }
        }
      },
      "ImageUuid": {
        "type": "object",
        "properties": {
          "media_uuid": {
            "description": "Id of media associated with this image",
            "type": "string"
          }
        }
      },
      "GetImage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ImageUuid"
          },
          {
            "type": "object",
            "properties": {
              "width": {
                "description": "Width (pixels) of image",
                "type": "integer"
              },
              "height": {
                "description": "Height (pixels) of image",
                "type": "integer"
              },
              "image_name": {
                "description": "The image name",
                "type": "string"
              },
              "image_size": {
                "description": "The size (in bytes) of the image",
                "type": "string"
              }
            }
          }
        ]
      },
      "GetImageMessage": {
        "description": "When `type = image`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/GetImageMessagePayload"
          }
        ]
      },
      "GetImageMessagePayload": {
        "description": "The user uploaded an image\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "image"
            ]
          },
          "image": {
            "$ref": "#/components/schemas/GetImage"
          }
        }
      },
      "FileUuid": {
        "type": "object",
        "properties": {
          "uuid": {
            "description": "Id associated with this file",
            "type": "string"
          }
        }
      },
      "GetFile": {
        "allOf": [
          {
            "$ref": "#/components/schemas/FileUuid"
          },
          {
            "type": "object",
            "properties": {
              "mime_type": {
                "description": "Mime type of the file",
                "type": "string"
              },
              "file_name": {
                "description": "File name",
                "type": "string"
              },
              "file_size": {
                "description": "The size (in bytes) of the file",
                "type": "string"
              }
            }
          }
        ]
      },
      "GetFileMessage": {
        "description": "When `type = file`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/GetFileMessagePayload"
          }
        ]
      },
      "GetFileMessagePayload": {
        "description": "The user uploaded a file\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "file"
            ]
          },
          "file": {
            "$ref": "#/components/schemas/GetFile"
          }
        }
      },
      "TextInputResponse": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "description": "value input by the user"
          },
          "type": {
            "type": "string",
            "description": "type field from the matching TextInput object"
          },
          "payload": {
            "type": "string",
            "description": "payload field from the matching TextInput object"
          }
        }
      },
      "TextInputResponseMessage": {
        "description": "When `type = text_input_response`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/TextInputResponseMessagePayload"
          }
        ]
      },
      "TextInputResponseMessagePayload": {
        "description": "User entered a response in the text input field\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text_input_response"
            ]
          },
          "text_input_response": {
            "$ref": "#/components/schemas/TextInputResponse"
          }
        }
      },
      "TextInputRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "password",
              "email",
              "text",
              "phone"
            ]
          },
          "title": {
            "type": "string",
            "description": "Prompt to display next to the text input field"
          },
          "regular_expression": {
            "type": "string",
            "description": "Regular expression which must be validated client-side before the TextInputResponse is sent back"
          },
          "payload": {
            "type": "string",
            "description": "value to pass back to the server in TextInputResponse"
          }
        }
      },
      "TextInputRequestMessage": {
        "description": "When `type = text_input`\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageBase"
          },
          {
            "$ref": "#/components/schemas/TextInputRequestMessagePayload"
          }
        ]
      },
      "TextInputRequestMessagePayload": {
        "description": "Brand is asking user to enter some text matching specific constraints\n",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text_input"
            ]
          },
          "text_input": {
            "$ref": "#/components/schemas/TextInputRequest"
          }
        }
      },
      "Message": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/StartMessage"
          },
          {
            "$ref": "#/components/schemas/PostbackMessage"
          },
          {
            "$ref": "#/components/schemas/TextMessage"
          },
          {
            "$ref": "#/components/schemas/ButtonMessage"
          },
          {
            "$ref": "#/components/schemas/GetImageMessage"
          },
          {
            "$ref": "#/components/schemas/GetFileMessage"
          },
          {
            "$ref": "#/components/schemas/TextInputResponseMessage"
          },
          {
            "$ref": "#/components/schemas/TextInputRequestMessage"
          },
          {
            "$ref": "#/components/schemas/CarouselMessage"
          }
        ]
      }
    },
    "securitySchemes": {
      "inmessage_authentication": {
        "description": "This is the authentication mecanism to authenticate most calls to the [InMessage API]() endpoints.\n",
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "inmessage_authentication": []
    }
  ],
  "paths": {
    "/{page_id}/conversation": {
      "get": {
        "parameters": [
          {
            "$ref": "#/components/parameters/page_id"
          },
          {
            "in": "query",
            "name": "max_message_id",
            "schema": {
              "type": "integer"
            },
            "description": "If specified, return only messages which verify the condition `message.id < max_message_id`"
          },
          {
            "in": "query",
            "name": "min_message_id",
            "schema": {
              "type": "integer"
            },
            "description": "If specified, return only messages which verify the condition `message.id > min_message_id`.\n"
          }
        ],
        "summary": "List messages",
        "tags": [
          "Conversation"
        ],
        "description": "Return up to 10 messages for the specified conversation, ordered by increasing message id. Paging can be performed by using the `min_message_id` parameter, initialized to zero and updated after each successful call to the max of the returned message ids + 1.\n",
        "responses": {
          "200": {
            "description": "returned upon success",
            "content": {
              "application/json": {
                "schema": {
                  "description": "list of matching messages",
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Conversation ID"
                    },
                    "last_seen_message_id": {
                      "type": "integer",
                      "description": "Max of all message IDs GETed by http client"
                    },
                    "messages": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Message"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached. Default limit is set to 15 requests per minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitResponseError"
                }
              }
            }
          }
        }
      }
    }
  }
}
```