Confirm a proposal: the return is created now. Pass termsAccepted: true when the card
showed summary.claimTerms and the shopper ticked them. Answers 409 PROPOSAL_NOT_PENDING
or PROPOSAL_EXPIRED when it can no longer be confirmed.
Start a conversation. Throws 403 ASSISTANT_DISABLED when the shop has the assistant off,
and 401 SIGN_IN_REQUIRED when config.access is signedIn and no customer is signed in.
Keep conversationId and token together; both are needed for everything after this.
Whether to show the chat, its name, greeting, what it can do, who may use it and the
suggested questions. Pass locale (e.g. "sv" or "en-GB") to get the questions in that
language.
Read a conversation. With after (an ISO time, typically the newest message's createdAt)
only newer messages are returned: poll this while the status is waiting or human to
receive the shop staff's replies. A wrong token answers 404 CONVERSATION_NOT_FOUND.
Recalculate a delivery card (another postal code or quantity), straight from the card and
without a model turn. The postal code becomes the conversation's. 400 DELIVERY_QUOTE_FAILED
when the postal code or products are not valid.
Decline a proposal. Nothing is created.
The shopper asks for a person. Contact details are optional but let the shop answer by
e-mail; message is saved as the shopper's note, businessUnitId the store they chose (see
AssistantResource.availability). Throws 403 HANDOVER_DISABLED when the shop has
handover off (config.capabilities.handover), and 400 EMAIL_REQUIRED when nobody is
available and no e-mail was given: ask for it (required) and send again. The returned
conversation carries handover (live, store, staffName).
Send the shopper's message (max 1000 characters) and stream the answer. The message may be
empty when photos go with it (attachmentIds).
onEvent receives each event as it arrives; the promise resolves when the server closes the
stream. Errors before the stream starts (validation, a wrong token, rate limits) reject with
a StorefrontApiError; a failure during the turn arrives as an error event and in
the result. Aborting signal resolves with aborted: true.
The streamed text has no message ids. Re-read the conversation afterwards when the ids or
the server's createdAt are needed (for example as the after cursor when polling).
Upload photos (for example of a damaged item) before sending the message they belong to.
jpeg, png or webp, at most 5 MB each and 3 per call (6 per conversation). The server
re-encodes them to webp without metadata. Pass the returned ids as attachmentIds to
AssistantResource.sendMessage.
files are Files from an <input type="file"> or plain Blobs (Node 18+ included; a
blob without a name is sent as photo-1.jpg and so on). Throws 403 ATTACHMENTS_DISABLED
when the shop has photos off (config.attachments.enabled), 422 TOO_MANY_ATTACHMENTS,
UNSUPPORTED_FILE_TYPE or FILE_TOO_LARGE.
Pass
locale, the same as the conversation starts with: someone available in a response group for that language counts as live too.