Queek docs
Merchant endpoint reference

Conversations

GET
/conversations

Requires scope merchant-conversations-read.

Lists the store’s messaging conversations (WhatsApp, Instagram and Telegram), newest first by creation, with cursor pagination (limit up to 50 + starting_after, has_more/next_cursor). status defaults to active; channel narrows to one line. Each conversation has its unread_count, last_message_preview, whether the AI or the team is answering (mode, is_human_mode_active, mode_expires_at) and its messaging_window: WhatsApp and Instagram allow a free-form reply only within 24 hours of the shopper’s last message (open, expires_at). customer.id is the store customer’s id when the shopper has signed in to the store; customer.name and customer.contact (the shopper’s phone number or channel handle) are null without merchant-customers-contact-read. Previews and message text are written by shoppers and can contain anything they typed, contact details included. Requires a store plan that includes the messaging inbox; without it the answer is the same 403 the dashboard gives. Whether the AI or the team answers cannot be changed through this API.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 50
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

status?|

Only items with this status.

Lengthlength <= 20
channel?|

Only items on this messaging channel: whatsapp, instagram or telegram. One of whatsapp, instagram, telegram.

Value in

  • "whatsapp"
  • "instagram"
  • "telegram"
  • null
app_id?string

Not accepted: the calling installation is identified by its key.

installation_id?string

Not accepted: the calling installation is identified by its key.

source?string

Not accepted: the source is the calling installation.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/conversations?limit=2&status=active&channel=whatsapp" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42",      "channel": "whatsapp",      "status": "active",      "mode": "ai",      "is_human_mode_active": false,      "mode_expires_at": null,      "unread_count": 2,      "last_message_preview": "Hi, is the smokehouse party pack ready for pickup at 5pm?",      "last_message_at": "2026-10-14T09:05:00+01:00",      "created_at": "2026-10-14T08:41:00+01:00",      "messaging_window": {        "channel": "whatsapp",        "applicable": true,        "hours": 24,        "last_inbound_at": "2026-10-14T09:05:00+01:00",        "expires_at": "2026-10-15T09:05:00+01:00",        "open": true      },      "customer": {        "id": 90341,        "is_customer": true,        "name": "Alex Morgan",        "contact": "12025550148"      }    },    {      "id": "019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f43",      "channel": "telegram",      "status": "active",      "mode": "ai",      "is_human_mode_active": false,      "mode_expires_at": null,      "unread_count": 0,      "last_message_preview": "Is the party pack still available for Saturday?",      "last_message_at": "2026-10-14T09:05:00+01:00",      "created_at": "2026-10-13T18:20:00+01:00",      "messaging_window": {        "channel": "telegram",        "applicable": false,        "hours": 24,        "last_inbound_at": "2026-10-14T09:05:00+01:00",        "expires_at": null,        "open": true      },      "customer": {        "id": 90341,        "is_customer": true,        "name": "Alex Morgan",        "contact": "884120937"      }    }  ],  "has_more": true,  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNCAwODo0MTowMCIsImlkIjoiMDE5YTRjMTAtN2UyYi03ZDMxLTlhNWYtM2I2YzhkMGUxZjQzIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}
GET
/conversations/{conversation}

Requires scope merchant-conversations-read.

Retrieves one conversation of this store with the same object as the list. {conversation} is the conversation id; another store’s conversation answers 404 like a missing one.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

conversation*string

Identifier of the conversation, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/conversations/019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Conversation retrieved.",  "data": {    "id": "019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42",    "channel": "whatsapp",    "status": "active",    "mode": "ai",    "is_human_mode_active": false,    "mode_expires_at": null,    "unread_count": 2,    "last_message_preview": "Hi, is the smokehouse party pack ready for pickup at 5pm?",    "last_message_at": "2026-10-14T09:05:00+01:00",    "created_at": "2026-10-14T08:41:00+01:00",    "messaging_window": {      "channel": "whatsapp",      "applicable": true,      "hours": 24,      "last_inbound_at": "2026-10-14T09:05:00+01:00",      "expires_at": "2026-10-15T09:05:00+01:00",      "open": true    },    "customer": {      "id": 90341,      "is_customer": true,      "name": "Alex Morgan",      "contact": "12025550148"    }  }}
GET
/conversations/{conversation}/messages

Requires scope merchant-conversations-read.

Lists a conversation’s messages, newest first, with cursor pagination (limit up to 50 + starting_after). sender.type is customer, merchant (the store’s team; a team member’s name is never returned), assistant (the store’s AI), app (sender.name and sender.app say which app) or system. Only image_url, button labels and a shared product’s name, picture and link are returned from a message’s extra data. content is written by the shopper or the team and is not masked. Same plan requirement and 404 rule as retrieving a conversation.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

conversation*string

Identifier of the conversation, as returned by the Merchant API.

Query Parameters

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 50
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

status?|

Only items with this status.

Lengthlength <= 20
channel?|

Only items on this messaging channel: whatsapp, instagram or telegram. One of whatsapp, instagram, telegram.

Value in

  • "whatsapp"
  • "instagram"
  • "telegram"
  • null
app_id?string

Not accepted: the calling installation is identified by its key.

installation_id?string

Not accepted: the calling installation is identified by its key.

source?string

Not accepted: the source is the calling installation.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/conversations/019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42/messages?limit=20" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "id": "019a4c11-0003-7a00-8b00-000000000003",      "type": "text",      "content": "Yes, it is ready. Come any time before 7pm.",      "sender": {        "type": "app",        "name": "Example Helpdesk",        "app": "example-helpdesk"      },      "image_url": null,      "buttons": [],      "product": null,      "created_at": "2026-10-14T09:07:00+01:00"    },    {      "id": "019a4c11-0002-7a00-8b00-000000000002",      "type": "text",      "content": "Hello Alex! The Smokehouse Party Pack is available. Shall I reserve one?",      "sender": {        "type": "assistant",        "name": null,        "app": null      },      "image_url": null,      "buttons": [],      "product": null,      "created_at": "2026-10-14T09:05:00+01:00"    },    {      "id": "019a4c11-0001-7a00-8b00-000000000001",      "type": "text",      "content": "Hi, is the smokehouse party pack ready for pickup at 5pm?",      "sender": {        "type": "customer",        "name": null,        "app": null      },      "image_url": null,      "buttons": [],      "product": null,      "created_at": "2026-10-14T09:04:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNCAwOTowNTowMCIsImlkIjoiMDE5YTRjMTEtMDAwMi03YTAwLThiMDAtMDAwMDAwMDAwMDAyIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}
POST
/conversations/{conversation}/messages

Requires scope merchant-conversations-reply.

Sends a reply to the shopper on the conversation’s own line (the store’s WhatsApp, Instagram or Telegram) and stores it on the thread, marked as sent by this app (the team sees sender_name " (app)"). type is text (content required), image (image_url required, content an optional caption) or product (product_id, a product of this store that is published, with product_format card or link); button messages are not available to apps. Send an Idempotency-Key header: it is required, and a retry with the same key and body replays the first answer instead of messaging the shopper twice. On WhatsApp and Instagram a free-form reply is allowed only within 24 hours of the shopper’s last message: after that the answer is 409 messaging_window_closed and nothing is sent. Telegram has no window. Replying pauses the store’s AI on this conversation for the store’s takeover window, as a dashboard reply does; the answer carries mode and mode_expires_at. If the channel refuses the message the answer is 424 channel_gateway_unreachable, nothing is stored, and the same request can be retried. Each installation may send 20 replies a minute and 1,000 a day (429 with Retry-After beyond that). Requires a store plan that includes the messaging inbox.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

conversation*string

Identifier of the conversation, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST conversations/{conversation}/messages — an app replying to a shopper.

Same body rules as the dashboard reply (it IS that request), narrowed for apps: no buttons (a button's action id is dispatched into the store's ordering bot when the shopper taps it) and a mandatory Idempotency-Key (a retried reply would otherwise message the shopper twice). The gate order is the row's scope, the calling installation, the store's plan (vendor_inboxes, inherited), the Idempotency-Key, then the installation's reply budget (spent only by a request that carries a key) — all before validation.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/conversations/019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42/messages" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "type": "text",    "content": "Yes, it is ready. Come any time before 7pm."  }'
{  "status": "success",  "message": "Reply sent.",  "data": {    "mode": "human",    "mode_expires_at": "2026-10-14 09:27:00",    "message": {      "id": "019a4c11-0003-7a00-8b00-000000000003",      "type": "text",      "content": "Yes, it is ready. Come any time before 7pm.",      "sender": {        "type": "app",        "name": "Example Helpdesk",        "app": "example-helpdesk"      },      "image_url": null,      "buttons": [],      "product": null,      "created_at": "2026-10-14T09:07:00+01:00"    }  }}
POST
/conversations/{conversation}/mark-read

Requires scope merchant-conversations-update.

Sets the conversation’s unread counter to zero for the store’s team, as opening it in the dashboard does. Nothing is sent to the shopper. Answers the conversation id and unread_count 0.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Path Parameters

conversation*string

Identifier of the conversation, as returned by the Merchant API.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/conversations/019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42/mark-read" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Marked as read.",  "data": {    "id": "019a4c10-7e2b-7d31-9a5f-3b6c8d0e1f42",    "unread_count": 0  }}