• English

      • Conversations API

      The Conversations API reads conversations for the authenticated shop. Complete Open Platform authentication before calling it.

      Base path:

      /open/v1/conversations

      You can list conversations and get one conversation with its messages. These requests are read-only. They do not mark a conversation as read.

      Conversation fields

      FieldTypeDescription
      idstringConversation ID.
      createdAtstring or nullCreation time in UTC.
      closedAtstring or nullClose time in UTC. null when the conversation is still open.
      lastMessageAtstring or nullTime of the last message in UTC. null when no message time has been recorded.
      firstTextstring or nullFirst message text.
      lastMessageTextstring or nullLast message text, shortened to 100 characters.
      customerNamestring or nullCustomer name.
      sourcePagestring or nullPage URL where the conversation started.
      sourceTitlestring or nullTitle of that page.
      tagsarrayConversation tags. Empty when there are none.
      readbooleanWhether the shop has read the conversation.
      botRepliedbooleanWhether the bot has replied.
      hasBotbooleanWhether a bot is participating.
      archivedbooleanWhether the conversation is archived.
      emailstring or nullCustomer email.
      phonestring or nullCustomer phone.
      ratingnumber or nullCustomer rating. null when the customer has not rated the conversation.
      ratingMessagestring or nullComment left with the rating.
      userAgentstring or nullBrowser user agent captured when the conversation started.

      Message fields

      Returned only when getting one conversation.

      FieldTypeDescription
      idstringMessage ID.
      typestringtext or frame-html.
      textstring or nullMessage text. For frame-html, this is the HTML content.
      createdAtstring or nullCreation time in UTC.
      senderNamestring or nullSender display name.
      senderTypestringcustomer or shop.

      List conversations

      POST /open/v1/conversations/search
Content-Type: application/json

      The request body is optional. An empty body {} returns the first page with the default page size, sorted by creation time.

      Request body:

      FieldRequiredDefaultDescription
      pageno1Page number, starting at 1.
      pageSizeno20Page size. Maximum is 50.
      orderBynonewestnewest sorts by creation time. lastMessage sorts by the last message.
      createdFromnononeInclude conversations created at or after this time. Example: 2026-09-01T00:00:00Z.
      createdTonononeInclude conversations created at or before this time. Example: 2026-09-30T23:59:59Z.
      lastMessageFromnononeInclude conversations whose last message is at or after this time. Example: 2026-09-01T00:00:00Z.
      lastMessageTonononeInclude conversations whose last message is at or before this time. Example: 2026-09-30T23:59:59Z.
      readnononetrue or false.
      archivednononetrue or false.
      hasBotnononetrue or false.
      botRepliednononetrue or false.
      closednononetrue or false.
      emailnononeExact customer email. Example: ada@example.com.
      tagsnononeEvery tag must match. Example: ["order", "vip"].

      createdFrom, createdTo, lastMessageFrom, and lastMessageTo use the same UTC ISO-8601 format: YYYY-MM-DDTHH:mm:ssZ. A time with an offset is also accepted, for example 2026-09-01T08:00:00+08:00. Do not send a date alone, such as 2026-09-01, or epoch milliseconds.

      page must be at least 1. pageSize must be from 1 to 50. orderBy must be newest or lastMessage. A start time must not be later than its end time. A malformed JSON body also returns 400.

      {
  "page": 1,
  "pageSize": 20,
  "orderBy": "lastMessage",
  "createdFrom": "2026-09-01T00:00:00Z",
  "createdTo": "2026-09-30T23:59:59Z",
  "archived": false,
  "closed": false,
  "botReplied": true,
  "email": "ada@example.com",
  "tags": ["order", "vip"]
}

      200 response:

      {
  "items": [
    {
      "id": "support-group-665f0c2e0f1a2b3c4d5e6f70",
      "createdAt": "2026-09-04T00:00:00Z",
      "closedAt": null,
      "lastMessageAt": "2026-09-04T00:05:00Z",
      "firstText": "Where is my order?",
      "lastMessageText": "It ships tomorrow.",
      "customerName": "Ada",
      "sourcePage": "https://example.myshopify.com/products/tote",
      "sourceTitle": "Tote",
      "tags": ["order"],
      "read": false,
      "botReplied": true,
      "hasBot": true,
      "archived": false,
      "email": "ada@example.com",
      "phone": null,
      "rating": null,
      "ratingMessage": null,
      "userAgent": "Mozilla/5.0"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

      An empty result is still 200, with items set to [] and total set to 0.

      Get one conversation

      GET /open/v1/conversations/{id}

      Path parameter:

      NameDescription
      idConversation ID.

      200 response:

      {
  "id": "support-group-665f0c2e0f1a2b3c4d5e6f70",
  "createdAt": "2026-09-04T00:00:00Z",
  "closedAt": null,
  "lastMessageAt": "2026-09-04T00:05:00Z",
  "firstText": "Where is my order?",
  "lastMessageText": "It ships tomorrow.",
  "customerName": "Ada",
  "sourcePage": "https://example.myshopify.com/products/tote",
  "sourceTitle": "Tote",
  "tags": ["order"],
  "read": false,
  "botReplied": true,
  "hasBot": true,
  "archived": false,
  "email": "ada@example.com",
  "phone": null,
  "rating": null,
  "ratingMessage": null,
  "userAgent": "Mozilla/5.0",
  "messages": [
    {
      "id": "665f0c2e0f1a2b3c4d5e6f71",
      "type": "text",
      "text": "Where is my order?",
      "createdAt": "2026-09-04T00:00:00Z",
      "senderName": "Ada",
      "senderType": "customer"
    },
    {
      "id": "665f0c2e0f1a2b3c4d5e6f72",
      "type": "text",
      "text": "It ships tomorrow.",
      "createdAt": "2026-09-04T00:05:00Z",
      "senderName": "Shop",
      "senderType": "shop"
    }
  ]
}

      messages is ordered from oldest to newest. It is [] when the conversation has no messages.

      Returns 404 when the ID does not exist for the authenticated shop.