# List conversation messages
## List conversation messages
> Lists conversation messages. This will return a maximum of 100 messages per page, with 10 as default. You can use the \`limit\` and \`pageToken\` query parameters to paginate the results. Learn more about pagination in the Common API Usage pagination section.
```json
{"openapi":"3.0.3","info":{"title":"Conversations","version":"v1"},"tags":[{"name":"conversation_message","description":"Manage the messages of a conversation."}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"conversationId":{"name":"conversationId","description":"The conversation ID","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"limit":{"name":"limit","in":"query","required":false,"schema":{"format":"int64","type":"integer"}},"pageToken":{"name":"pageToken","in":"query","required":false,"schema":{"type":"string"}},"reverse":{"name":"reverse","in":"query","required":false,"schema":{"type":"boolean"}},"queryDateFrom":{"in":"query","name":"dateFrom","description":"Filter by created date after this date.","schema":{"type":"string","format":"date-time"}}},"schemas":{"MessageList":{"type":"object","properties":{"results":{"type":"array","description":"List of messages in the conversation.","items":{"$ref":"#/components/schemas/Message"}}}},"Message":{"type":"object","description":"A conversation message.","additionalProperties":false,"required":["id","sender","draft","status","source","createdAt","updatedAt"],"anyOf":[{"required":["body"]},{"required":["template"]}],"properties":{"id":{"type":"string","description":"Message ID.","minLength":1},"conversationId":{"type":"string","description":"Conversation ID.","minLength":1},"reference":{"type":"string","description":"A customizable ID assigned to messages you send. This can be used to correlate messages with data from your own integrating services. Must be globally unique within a workspace.\n"},"sender":{"$ref":"#/components/schemas/Participant"},"draft":{"type":"boolean","description":"Whether this message is a draft."},"draftMeta":{"$ref":"#/components/schemas/DraftMessageMeta"},"replyToMessageId":{"type":"string","format":"uuid"},"recipients":{"type":"array","description":"Recipient list of this message.","items":{"$ref":"#/components/schemas/MessageRecipient"}},"status":{"$ref":"#/components/schemas/MessageStatus"},"source":{"type":"string","description":"Whether the message was created by Bird's Conversations API or an external party.","enum":["conversations","external"]},"template":{"$ref":"#/components/schemas/Template"},"body":{"$ref":"#/components/schemas/Body"},"reason":{"type":"string","description":"Failure reason. Will be populated if the status is `sending_failed` or `delivery_failed`."},"interactions":{"type":"array","description":"A list of interactions associated with the message.","nullable":true,"items":{"type":"object","description":"A message interaction.","additionalProperties":false,"required":["id","type","createdAt"],"properties":{"id":{"type":"string","format":"uuid","description":"A unique identifier for that interaction within its message."},"type":{"type":"string","description":"The type of interaction. `read` means the message was acknowledged as read, `opened means the email was opened, `click` means a link or button in the message was clicked, `report-as-spam` means the email was marked as spam by the recipient, `unsubscribe-request` means the recipient unsubscribed from receiving further emails, `delete-request` is a request for a message to be deleted, `reaction` represents an emoji reaction, and `invalid` means the interaction type is unknown.\n","enum":["read","opened","clicked","reported-as-spam","unsubscribe-request","delete-request","reaction","invalid"]},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"},"metadata":{"type":"object","description":"Metadata is a free-form object that can be used to store any additional information such as platform specific information\n","additionalProperties":true,"properties":{"link":{"type":"object","description":"Clicked link data. Will be populated if the interaction type is `clicked`.","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"button":{"type":"object","description":"Clicked button data. Will be populated if the interaction type is `clicked` on a message with buttons.","properties":{"payload":{"type":"string"}}},"reaction":{"type":"object","description":"Reaction data. Will be populated if the interaction type is `reaction`.","properties":{"emoji":{"type":"string"},"action":{"type":"string"}}}}}}}},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"},"updatedAt":{"type":"string","description":"Update timestamp formatted as RFC3339.","format":"date-time"},"meta":{"$ref":"#/components/schemas/MessageMeta"},"receiverTypes":{"description":"ReceiverTypes list of types of receivers for the message. It can be `to`, `cc` and `bcc` at the moment. Currently only use for inbound email platforms messages.\n","type":"array","items":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]}},"inbox":{"$ref":"#/components/schemas/InboxRef"}}},"Participant":{"type":"object","description":"A participant who can send and receive messages in the conversation","title":"ConversationParticipant","additionalProperties":false,"properties":{"id":{"type":"string","description":"Participant ID, the meaning of this field depends on `type`. If `type` is `user` then it's a user ID, if `type` is `contact` then it's a contact ID, if `type` is `accessKey` then it's the access key ID, and so on.\n"},"displayName":{"type":"string","description":"The participant's name."},"avatarUrl":{"type":"string","description":"An URL to the participant's avatar."},"contact":{"$ref":"#/components/schemas/ParticipantContact"},"type":{"$ref":"#/components/schemas/ParticipantType"},"status":{"type":"string","description":"Participant status in the conversation. `pending` means it's pending approval, `invited` means it's pending acceptance from the participant, and `active` means the participant can send and receive messages.\n","enum":["pending","invited","active"],"default":"active"}},"required":["id","type"]},"ParticipantContact":{"type":"object","description":"The participant's contact information. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used."},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddress":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."}}},"ParticipantType":{"type":"string","description":"Participant type. The main ones are `user`, `contact`, and `agent`. `user` is a user belonging to your Bird workspace, `contact` is one of your customers, `agent` is a customer service agent, and the remaining types represent system participants.\n","enum":["user","contact","agent","flow","bot","accessKey","channel","connector","collaborationAutomation"]},"DraftMessageMeta":{"type":"object","description":"Metadata for draft messages.","additionalProperties":false,"required":["creatorType"],"properties":{"creatorType":{"type":"string","description":"The type of creator of the draft message.","enum":["bot","user"]}}},"MessageRecipient":{"type":"object","description":"Participant who receives a message.","title":"MessageRecipient","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"Participant ID."},"type":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]},"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n"},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n"},"platformAddress":{"type":"string"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."},"contactAnnotation":{"type":"object","description":"Contains the name of the contact","properties":{"name":{"nullable":true,"type":"string","description":"Contact name"}}},"isInbox":{"type":"boolean","description":"Indicates whether the recipient is the inbox."}}},"MessageStatus":{"type":"string","description":"Message status. The lifecycle order is `accepted`, `processing`, `sent`, and `delivered`.","enum":["accepted","processing","sent","sending_failed","delivered","delivery_failed","deleted"]},"Template":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"name":{"type":"string","description":"The platform name of the template."},"projectId":{"type":"string","description":"the ID of the project from the project from Studio"},"version":{"type":"string","description":"The version of the template."},"locale":{"type":"string","format":"locale-bcp47"},"attachments":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl","filename"],"properties":{"mediaUrl":{"type":"string","format":"uri","description":"The URL of the attachment."},"filename":{"type":"string","description":"The filename of the attachment."},"inline":{"type":"boolean"}}}},"shortLinks":{"nullable":true,"type":"object","description":"SMS link shortening options.","properties":{"enabled":{"type":"boolean","description":"Enables link shortening for SMS messages."},"domain":{"type":"string","description":"The domain to use when shortening links. When set to `default`,\nuses the default link shortening domain for the workspace.\n"}}},"variables":{"nullable":true,"deprecated":true,"description":"Deprecated: Use `parameters` instead (string parameter for variables). This property is maintained for backward compatibility but will be removed in a future version.\n","type":"object","properties":{"default":{"type":"string"}},"additionalProperties":{"type":"string"}},"utmParameters":{"nullable":true,"type":"array","description":"The list of UTM parameters.","minItems":1,"maxItems":8,"items":{"oneOf":[{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","description":"The name of the parameter in the query string.","minLength":1,"maxLength":20},"value":{"type":"string","description":"The static value of the parameter. Mutually exclusive with Reference.","minLength":1,"maxLength":100}}},{"type":"object","required":["key","reference"],"additionalProperties":false,"properties":{"key":{"type":"string","description":"The name of the parameter in the query string.","minLength":1,"maxLength":20},"reference":{"type":"string","description":"The reference to a dynamic value. Mutually exclusive with Value.","enum":["platform_name","channel_name"]}}}]}},"parameters":{"nullable":true,"type":"array","minLength":1,"items":{"$ref":"#/components/schemas/TemplateParameter"}},"settings":{"nullable":true,"type":"object","properties":{"disallowMmLite":{"type":"boolean","nullable":true,"description":"This is specific for WhatsApp marketing templates and requires MM Lite to be disabled for the WABAID.\n"}}}}},"TemplateParameter":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["string"]},"key":{"type":"string","minLength":1},"value":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["number"]},"key":{"type":"string","minLength":1},"value":{"type":"number"}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["boolean"]},"key":{"type":"string","minLength":1},"value":{"type":"boolean"}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["object"]},"key":{"type":"string","minLength":1},"value":{"type":"object","additionalProperties":true}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["sectionList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["sections"],"additionalProperties":false,"properties":{"sections":{"$ref":"#/components/schemas/Sections"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["timeslotList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["timeslots"],"additionalProperties":false,"properties":{"timeslots":{"$ref":"#/components/schemas/Timeslots"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["productSections"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["productSections"],"additionalProperties":false,"properties":{"productSections":{"$ref":"#/components/schemas/ProductSections"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["productList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["products"],"additionalProperties":false,"properties":{"products":{"$ref":"#/components/schemas/ProductList"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["shippingMethodList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["shippingMethods"],"additionalProperties":false,"properties":{"shippingMethods":{"$ref":"#/components/schemas/AppleShippingMethods"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["lineItemList"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["lineItems"],"additionalProperties":false,"properties":{"lineItems":{"$ref":"#/components/schemas/AppleLineItems"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["whatsappProductSections"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["sections"],"additionalProperties":false,"properties":{"sections":{"$ref":"#/components/schemas/WhatsappProductSections"}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["whatsappProductItems"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["products"],"additionalProperties":false,"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/WhatsappProductItem"}}}}}},{"type":"object","additionalProperties":false,"required":["type","key"],"properties":{"type":{"type":"string","enum":["carouselCards"]},"key":{"type":"string","minLength":1},"value":{"type":"object","required":["cards"],"additionalProperties":false,"properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/WhatsappCarouselCard"}}}}}}]},"Sections":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["title","items"],"properties":{"id":{"type":"string","nullable":true},"multipleSelection":{"type":"boolean"},"title":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReplyAction"}}}}},"ReplyAction":{"type":"object","required":["type","replyAction"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["reply-action"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"replyAction":{"type":"object","properties":{"text":{"type":"string"},"imageUrl":{"type":"string"},"payload":{"type":"string"},"subTitle":{"type":"string"}},"required":["text"]}}},"Timeslots":{"type":"array","nullable":false,"items":{"type":"object","additionalProperties":false,"required":["startTime","duration"],"properties":{"id":{"type":"string","nullable":true},"startTime":{"type":"string","format":"date-time"},"duration":{"type":"number"}}}},"ProductSections":{"type":"array","nullable":false,"items":{"type":"object","additionalProperties":false,"required":["title","products"],"properties":{"title":{"type":"string","minLength":1,"maxLength":24},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"Product":{"type":"object","additionalProperties":false,"required":["externalProductId"],"properties":{"externalProductId":{"type":"string"},"amount":{"type":"string"},"text":{"type":"string"}}},"ProductList":{"type":"array","nullable":false,"items":{"type":"object","additionalProperties":false,"required":["type","product"],"properties":{"type":{"type":"string","enum":["product"]},"product":{"$ref":"#/components/schemas/Product"}}}},"AppleShippingMethods":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["amount","label","identifier","detail"],"properties":{"amount":{"type":"string"},"label":{"type":"string"},"identifier":{"type":"string"},"detail":{"type":"string"}}}},"AppleLineItems":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["amount","text"],"properties":{"amount":{"type":"string"},"text":{"type":"string"},"type":{"type":"string","enum":["pending","final"]}}}},"WhatsappProductSections":{"type":"array","nullable":false,"items":{"$ref":"#/components/schemas/WhatsappProductSection"}},"WhatsappProductSection":{"type":"object","additionalProperties":false,"required":["type","whatsappProductSection"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["whatsapp-product-section"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"whatsappProductSection":{"type":"object","additionalProperties":false,"required":["title","products"],"properties":{"title":{"type":"string","minLength":1,"maxLength":24},"products":{"type":"array","items":{"$ref":"#/components/schemas/WhatsappProductItem"}}}}}},"WhatsappProductItem":{"type":"object","additionalProperties":false,"required":["type","whatsappProductItem"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["whatsapp-product-item"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"whatsappProductItem":{"type":"object","additionalProperties":false,"required":["externalProductId"],"properties":{"externalProductId":{"type":"string"}}}}},"WhatsappCarouselCard":{"type":"object","additionalProperties":false,"required":["type","whatsappCarouselCard"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["whatsapp-carousel-card"]},"reference":{"type":"string"},"role":{"type":"string"},"hidden":{"type":"boolean"},"whatsappCarouselCard":{"type":"object","additionalProperties":false,"required":["header","body","actions"],"properties":{"header":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","image"],"properties":{"type":{"type":"string","enum":["image"]},"image":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"mediaUrl":{"type":"string"},"altText":{"type":"string"}}}}},{"type":"object","additionalProperties":false,"required":["type","file"],"properties":{"type":{"type":"string","enum":["file"]},"file":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"mediaUrl":{"type":"string"},"contentType":{"type":"string"}}}}}]},"body":{"type":"object","additionalProperties":false,"required":["type","text"],"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string"}}}}},"actions":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["type","linkAction"],"properties":{"type":{"type":"string","enum":["link-action"]},"linkAction":{"type":"object","additionalProperties":false,"required":["text","url"],"properties":{"text":{"type":"string"},"url":{"type":"string"}}}}},"minItems":1,"maxItems":1,"description":"Session carousels only support one link action per card."}}}}},"Body":{"type":"object","title":"MessageBody","nullable":true,"allOf":[{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/BodyTypes"}}},{"oneOf":[{"$ref":"#/components/schemas/TypeText"},{"$ref":"#/components/schemas/TypeHTML"},{"$ref":"#/components/schemas/TypeImage"},{"$ref":"#/components/schemas/TypeFile"},{"$ref":"#/components/schemas/TypeGif"},{"$ref":"#/components/schemas/TypeLocation"},{"$ref":"#/components/schemas/TypeCarousel"},{"$ref":"#/components/schemas/TypeList"},{"$ref":"#/components/schemas/TypeSection"},{"$ref":"#/components/schemas/TypeAuthentication"},{"$ref":"#/components/schemas/TypeAction"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TypeText","html":"#/components/schemas/TypeHTML","image":"#/components/schemas/TypeImage","file":"#/components/schemas/TypeFile","gif":"#/components/schemas/TypeGif","location":"#/components/schemas/TypeLocation","carousel":"#/components/schemas/TypeCarousel","list":"#/components/schemas/TypeList","section":"#/components/schemas/TypeSection","authentication":"#/components/schemas/TypeAuthentication","action":"#/components/schemas/TypeAction"}}}]},"BodyTypes":{"type":"string","enum":["text","html","image","file","gif","location","carousel","list","section","authentication","template","action"]},"TypeText":{"type":"object","required":["text","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1},"attachments":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl","filename"],"properties":{"mediaUrl":{"type":"string","format":"uri"},"filename":{"type":"string"},"inline":{"type":"boolean"},"contentId":{"type":"string"}}}},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","additionalProperties":false,"properties":{"subject":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"whatsapp":{"type":"object","additionalProperties":false,"properties":{"previewUrl":{"type":"boolean","description":"When set to `true`, preview will be displayed within whatsapp chat."}}},"line":{"type":"object","additionalProperties":false,"properties":{"emoji":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"required":["index","productId","emojiId"],"properties":{"index":{"type":"integer"},"productId":{"type":"string"},"emojiId":{"type":"string"},"length":{"type":"integer","nullable":true,"readOnly":true}}}}}}}},"telegram":{"$ref":"#/components/schemas/MetadataTelegram"},"apple":{"$ref":"#/components/schemas/MetadataApple"}}}}}}},"Actions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Action"}},"Action":{"allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["link","reply","locationRequest","buy","postback"]}}},{"oneOf":[{"$ref":"#/components/schemas/ActionLink"},{"$ref":"#/components/schemas/ActionReply"},{"$ref":"#/components/schemas/ActionLocationRequest"},{"$ref":"#/components/schemas/ActionBuy"},{"$ref":"#/components/schemas/ActionPostback"}],"discriminator":{"propertyName":"type","mapping":{"link":"#/components/schemas/ActionLink","reply":"#/components/schemas/ActionReply","locationRequest":"#/components/schemas/ActionLocationRequest","buy":"#/components/schemas/ActionBuy","postback":"#/components/schemas/ActionPostback"}}}]},"ActionLink":{"type":"object","required":["link","type"],"properties":{"type":{"type":"string","enum":["link"]},"link":{"type":"object","required":["text","url"],"properties":{"text":{"type":"string"},"url":{"anyOf":[{"type":"string","pattern":"{{[^{}]+}}"},{"type":"string","format":"uri"}]}}}}},"ActionReply":{"type":"object","required":["reply","type"],"properties":{"type":{"type":"string","enum":["reply"]},"reply":{"type":"object","properties":{"text":{"type":"string"},"imageUrl":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ActionReplyMetadata"}},"required":["text"]}}},"ActionReplyMetadata":{"type":"object","properties":{"description":{"$ref":"#/components/schemas/ActionDescription"}}},"ActionDescription":{"type":"object","description":"Sets the description in the row objects for Whatsapp list messages. Only available usage for Whatsapp platform","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":72}}},"ActionLocationRequest":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["locationRequest"]},"locationRequest":{"type":"object","nullable":true,"properties":{"text":{"type":"string","default":"Send location"}}}}},"ActionBuy":{"type":"object","required":["buy","type"],"properties":{"type":{"type":"string","enum":["buy"]},"buy":{"type":"object","properties":{"text":{"type":"string"},"amountCents":{"type":"integer"},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["text","amountCents","currency"]}}},"ActionPostback":{"type":"object","required":["postback","type"],"properties":{"type":{"type":"string","enum":["postback"]},"postback":{"type":"object","properties":{"text":{"type":"string"},"payload":{"type":"string"},"imageUrl":{"type":"string"},"metadata":{"$ref":"#/components/schemas/ActionPostbackMetadata"}},"required":["text"]}}},"ActionPostbackMetadata":{"type":"object","properties":{"description":{"$ref":"#/components/schemas/ActionDescription"}}},"MetadataTelegram":{"type":"object","description":"The property is specific to Telegram, indicating the markup type to be used for message formatting","additionalProperties":false,"properties":{"parseMode":{"type":"string","enum":["Markdown","MarkdownV2"]}}},"MetadataApple":{"type":"object","description":"The property is specific to Apple Business Chat, containing Apple-specific metadata","additionalProperties":false,"properties":{"summaryText":{"type":"string","description":"Summary text for Apple Business Chat messages"},"appClipPreview":{"type":"boolean","description":"Indicates if the message includes an App Clip link"},"appClipRegion":{"type":"string","description":"AppClipRegion is the ISO 3166 alpha-2 country code for the App Store region."}}},"TypeHTML":{"type":"object","required":["html","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["html"]},"html":{"type":"object","additionalProperties":false,"anyOf":[{"required":["text"]},{"required":["html"]}],"properties":{"text":{"type":"string","minLength":1},"html":{"type":"string","minLength":1},"attachments":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"anyOf":[{"required":["mediaUrl","filename"]},{"required":["content","contentType","filename"]}],"properties":{"mediaUrl":{"type":"string","format":"uri"},"filename":{"type":"string"},"inline":{"type":"boolean"},"content":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"contentId":{"type":"string"}}}},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","additionalProperties":false,"properties":{"subject":{"type":"string"},"emailFrom":{"type":"object","additionalProperties":false,"properties":{"username":{"type":"string","pattern":"[\\w\\d.-/+]+"},"displayName":{"type":"string"}}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"initialOpenTracking":{"type":"boolean"},"clickTracking":{"type":"boolean"},"openTracking":{"type":"boolean"}}}}}}},"TypeImage":{"type":"object","required":["image","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["image"]},"image":{"type":"object","additionalProperties":false,"required":["images"],"properties":{"text":{"type":"string"},"images":{"type":"array","minLength":1,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"mediaUrl":{"type":"string","format":"uri","minLength":1},"altText":{"type":"string"}}}},"metadata":{"type":"object","properties":{"subject":{"type":"string","description":"The property is specific mms file, shows the subject of the mms."},"fallbackText":{"type":"string","description":"The property is specific mms file, when a mms is not supported, it will fallback to show content with the fallbackText."},"storyType":{"type":"string","description":"The property is specific instagram file, shows the story type."},"telegram":{"$ref":"#/components/schemas/MetadataTelegram"}}},"actions":{"$ref":"#/components/schemas/Actions"}}}}},"TypeFile":{"type":"object","required":["file","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["file"]},"file":{"type":"object","additionalProperties":false,"required":["files"],"properties":{"text":{"type":"string"},"files":{"type":"array","minLength":1,"items":{"type":"object","additionalProperties":false,"required":["mediaUrl","contentType"],"properties":{"mediaUrl":{"type":"string","format":"uri","minLength":1},"contentType":{"type":"string","minLength":1},"filename":{"type":"string"},"altText":{"type":"string"},"metadata":{"type":"object","properties":{"isAnimated":{"type":"boolean","description":"The property is specific the sticker file, shows that if the sticker is animated or not."}}}}}},"metadata":{"type":"object","properties":{"subject":{"type":"string","description":"The property is specific mms file, shows the subject of the mms."},"fallbackText":{"type":"string","description":"The property is specific mms file, when a mms is not supported, it will fallback to show content with the fallbackText."},"storyType":{"type":"string","description":"The property is specific instagram file, shows the story type."},"telegram":{"$ref":"#/components/schemas/MetadataTelegram"}}},"actions":{"$ref":"#/components/schemas/Actions"}}}}},"TypeGif":{"type":"object","required":["gif","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["gif"]},"gif":{"type":"object","additionalProperties":false,"required":["mediaUrl"],"properties":{"text":{"type":"string"},"mediaUrl":{"type":"string","format":"uri","minLength":1},"altText":{"type":"string"},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","properties":{"telegram":{"$ref":"#/components/schemas/MetadataTelegram"}}}}}}},"TypeLocation":{"type":"object","required":["location","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["location"]},"location":{"type":"object","additionalProperties":false,"required":["coordinates"],"properties":{"coordinates":{"type":"object","additionalProperties":false,"properties":{"latitude":{"type":"number","format":"float","minimum":-90,"maximum":90},"longitude":{"type":"number","format":"float","minimum":-180,"maximum":180}}},"location":{"type":"object","additionalProperties":false,"properties":{"address":{"type":"string"},"label":{"type":"string"}}}}}}},"TypeCarousel":{"type":"object","required":["carousel","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["carousel"]},"carousel":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"text":{"type":"string","description":"Optional text displayed above the carousel cards","maxLength":1024},"items":{"$ref":"#/components/schemas/Items"}}}}},"Items":{"type":"array","nullable":true,"items":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"mediaUrl":{"type":"string","format":"uri","nullable":true},"description":{"type":"string"},"altText":{"type":"string"},"actions":{"$ref":"#/components/schemas/Actions"}}}},"TypeList":{"type":"object","required":["list","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["list"]},"list":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string"},"text":{"type":"string"},"altText":{"type":"string"},"items":{"$ref":"#/components/schemas/Items"},"actions":{"$ref":"#/components/schemas/Actions"},"metadata":{"type":"object","properties":{"button":{"type":"object","description":"Sets a button name for whatsapp list messages. Only available usage for Whatsapp platform","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":20}}},"replyMessage":{"type":"object","description":"Sets the reply message to be used when a list item is picked. Used for Apple Business Chat.","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":512},"text":{"type":"string","maxLength":512}}}}}},"required":["text"]}}},"TypeSection":{"type":"object","required":["section","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["section"]},"section":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","items":{"minLength":1,"$ref":"#/components/schemas/SectionBody"}},"configurations":{"type":"object","additionalProperties":{"type":"string"}}}}}},"SectionBody":{"type":"object","title":"MessageBody","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","image","file","gif","location","carousel","list","section"]}}},{"oneOf":[{"$ref":"#/components/schemas/TypeText"},{"$ref":"#/components/schemas/TypeImage"},{"$ref":"#/components/schemas/TypeFile"},{"$ref":"#/components/schemas/TypeGif"},{"$ref":"#/components/schemas/TypeLocation"},{"$ref":"#/components/schemas/TypeCarousel"},{"$ref":"#/components/schemas/TypeList"},{"$ref":"#/components/schemas/TypeSectionNested"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TypeText","image":"#/components/schemas/TypeImage","file":"#/components/schemas/TypeFile","gif":"#/components/schemas/TypeGif","location":"#/components/schemas/TypeLocation","carousel":"#/components/schemas/TypeCarousel","list":"#/components/schemas/TypeList","section":"#/components/schemas/TypeSectionNested"}}}]},"TypeSectionNested":{"type":"object","required":["section","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["section"]},"section":{"type":"object","additionalProperties":false,"properties":{"items":{"type":"array","items":{"minLength":1,"$ref":"#/components/schemas/SectionBodyNested"}},"configurations":{"type":"object","properties":{"default":{"type":"string"}},"additionalProperties":{"type":"string"}}}}}},"SectionBodyNested":{"type":"object","title":"MessageBody","allOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","image","file","gif","location","carousel","list"]}}},{"oneOf":[{"$ref":"#/components/schemas/TypeText"},{"$ref":"#/components/schemas/TypeImage"},{"$ref":"#/components/schemas/TypeFile"},{"$ref":"#/components/schemas/TypeGif"},{"$ref":"#/components/schemas/TypeLocation"},{"$ref":"#/components/schemas/TypeCarousel"},{"$ref":"#/components/schemas/TypeList"}],"discriminator":{"propertyName":"type","mapping":{"text":"#/components/schemas/TypeText","image":"#/components/schemas/TypeImage","file":"#/components/schemas/TypeFile","gif":"#/components/schemas/TypeGif","location":"#/components/schemas/TypeLocation","carousel":"#/components/schemas/TypeCarousel","list":"#/components/schemas/TypeList"}}}]},"TypeAuthentication":{"type":"object","required":["authentication","type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["authentication"]},"authentication":{"type":"object","additionalProperties":false,"properties":{"otp":{"type":"object","additionalProperties":false,"required":["disclaimer"],"properties":{"disclaimer":{"type":"boolean","description":"Whether to add a security disclaimer to the authentication body.","nullable":false},"expirationTime":{"type":"integer","minimum":1,"maximum":90,"nullable":true,"description":"The number of seconds after which the authentication body will expire. If not set, no expiration notification will be sent."},"actions":{"$ref":"#/components/schemas/Actions"}}}}}}},"TypeAction":{"type":"object","required":["type"],"additionalProperties":false,"properties":{"type":{"type":"string","enum":["permission_request"]},"permission_request":{"type":"object","required":["resource"],"properties":{"resource":{"type":"string","enum":["call"]}}}}},"MessageMeta":{"type":"object","description":"Message metadata fields that might be populated depending on the channel being used.","title":"MessageMeta","additionalProperties":false,"properties":{"email":{"type":"object","description":"Metadata fields for email messages.","additionalProperties":false,"properties":{"subject":{"type":"string","description":"Email subject line."},"headers":{"type":"object","description":"Additional email headers.","additionalProperties":{"type":"string"}},"from":{"type":"object","description":"Email From address.","additionalProperties":false,"properties":{"username":{"type":"string","description":"The username part of the adress, e.g. for the address `john.doe@bird.com`, this value will be `john.doe`.\n","pattern":"[\\w\\d.-/+]+"},"displayName":{"type":"string","description":"The display name of an email participant."}}}}},"extraInformation":{"type":"object","description":"A free-form object that might contain additional metadata fields.","additionalProperties":true},"referral":{"type":"object","description":"This represents a social media post or an ad that was referenced when starting the conversation.","additionalProperties":false,"properties":{"source":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"group":{"type":"string"},"metadata":{"type":"object","additionalProperties":false,"properties":{"sourceId":{"type":"string","description":"The ID of the social media post or ad."},"sourceUrl":{"type":"string","description":"The URL of the social media post or ad."},"mediaType":{"type":"string","description":"Type of media used in the post or ad."},"mediaUrl":{"type":"string","description":"Link to the media associated with the referral post or ad."},"caption":{"type":"string","description":"Caption associated with the referral post or ad."},"username":{"type":"string","description":"Username who created the referral post or ad."},"timestamp":{"type":"string","description":"Timestamp when the referral post or ad was created.","format":"date-time"},"trackingId":{"type":"string"}}}}}}},"InboxRef":{"type":"object","description":"A reference to an inbox.","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of the inbox."},"identifier":{"$ref":"#/components/schemas/WorkspaceIdentifier"},"ownerId":{"type":"string","format":"uuid","description":"The ID of the owner of the inbox."},"ownerType":{"$ref":"#/components/schemas/InboxOwnerType"},"type":{"$ref":"#/components/schemas/InboxType"}},"required":["id","identifier","ownerId","ownerType","type"]},"WorkspaceIdentifier":{"type":"string","pattern":"^[a-z0-9._-]+$","description":"The identifier of the resource inside the workspace. Takes the form of the user component of an email address.\n"},"InboxOwnerType":{"type":"string","enum":["user","group"]},"InboxType":{"type":"string","enum":["personal","shared","support"]},"Pagination":{"type":"object","properties":{"nextPageToken":{"type":"string","description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display."},"total":{"type":"integer","format":"uint64"},"totalType":{"type":"string","enum":["","equal","greaterThanOrEqual"]}}},"GenericError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"NotFoundError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"ConflictError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]}},"responses":{"forbidden":{"description":"User has no access to the requested resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}},"notFound":{"description":"The resource specified in the URL was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"conflict":{"description":"The resource is in a conflicting state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictError"}}}}}},"paths":{"/workspaces/{workspaceId}/conversations/{conversationId}/messages":{"get":{"summary":"List conversation messages","operationId":"listConversationMessages","description":"Lists conversation messages. This will return a maximum of 100 messages per page, with 10 as default. You can use the `limit` and `pageToken` query parameters to paginate the results. Learn more about pagination in the Common API Usage pagination section.\n","tags":["conversation_message"],"parameters":[{"$ref":"#/components/parameters/conversationId"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/pageToken"},{"$ref":"#/components/parameters/reverse"},{"$ref":"#/components/parameters/queryDateFrom"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/MessageList"},{"$ref":"#/components/schemas/Pagination"}]}}}},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"}}}}}}
```
## Examples
{% tabs %}
{% tab title="Request" %}
```bash
curl "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/16e1df9e-c6ac-406b-b1ce-13f34d0dea08/messages" \
-H "Authorization: AccessKey abcd"
```
{% endtab %}
{% tab title="Response (200 - OK)" %}
```json
{
"results": [
{
"id": "0c854061-6026-48c7-a2e8-bffb6458727b",
"conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08",
"reference": "",
"sender": {
"id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
"type": "accessKey",
"status": "active",
"displayName": "My first email key",
"avatarUrl": ""
},
"draft": false,
"recipients": [
{
"type": "to",
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"identifierKey": "emailaddress",
"identifierValue": "some.customer@example.com",
"platformAddress": "some.customer@example.com",
"contactAnnotation": {
"name": "John Doe"
}
}
],
"status": "delivered",
"source": "conversations",
"body": {
"type": "text",
"text": {
"text": "Hey, listen!"
}
},
"interactions": null,
"createdAt": "2024-11-25T20:12:10.514Z",
"updatedAt": "2024-11-25T20:12:35.281Z"
},
{
"id": "3e75a9d2-2a54-45ac-856a-bbe02f874332",
"conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08",
"reference": "3e75a9d2-2a54-45ac-856a-bbe02f874332",
"sender": {
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {
"identifierKey": "emailaddress",
"identifierValue": "some.customer@example.com",
"platformAddress": "some.customer@example.com",
}
},
"draft": false,
"status": "delivered",
"source": "channels",
"body": {
"type": "html",
"html": {
"text": "test\r\n",
"html": "test
"
}
},
"interactions": null,
"createdAt": "2024-11-25T19:31:47.264Z",
"updatedAt": "2024-11-25T19:31:47.264Z",
"meta": {
"extraInformation": {
"email_headers": "eyJTdWJqZWN0IjpbInRlc3QiXX0="
}
},
"receiverTypes": [
"to"
]
}
]
}
```
{% endtab %}
{% endtabs %}
**Note**: if the conversation has more than 10 messages, the results may be paginated. Please refer to [Pagination](https://docs.bird.com/api/api-access/common-api-usage#pagination) on how to use `nextPageToken`.