ShopperMessage is one moment of a purchase that a shopper should hear about, read from an Agentcard event and ready to post into that shopper’s chat. agentcard.listen and agentcardWebhook hand your onMessage one for each such event, together with your own id for the shopper.
messages.ts
recordOrder and postToChat stand for your own code. The listener records each placed order and posts each message’s text into the right chat. Give a switch over kind a default branch that sends text, because Agentcard can add a kind later.
ShopperMessage
A message about the shopper alone, such as a saved card, has both
threadId and conversationId set to null and belongs to every chat.
Send text when you have no agent, and for every message that carries a link, so the link arrives exactly as Agentcard wrote it. Hand note to your agent as a turn when you want the agent to say it in its own voice. When a message has no note, or your agent cannot run the turn, send text.
Kinds
kind is one of the values below. The last two columns say whether the message sets advances, and which link it ends.
The first eighteen kinds arrive as
purchase.message events. order_confirmed arrives as order.confirmed, and order_updated arrives as order.updated. A message whose kind is approval_expiring or card_link_unfinished leaves its link open.
ShopperFacts
The values of a message one by one. A fact that does not apply to the message is absent.
A message is stale once
validUntil has passed. Drop a stale message instead of sending it. isStale(message) checks it, and listen and agentcardWebhook do so for you.
LinkPaymentFacts
charge says how a purchase paid with Link ended at the store:
buy.walletOutcome(message) reads it for you: on none it cancels the Link payment at once, and it answers the line to post in place of text. See Read how a Link payment ended.
OrderStatus
orderStatus is one of confirmed, courier_assigned, courier_at_store, ready_for_pickup, picked_up, arriving, delivered or canceled. A stage Agentcard adds later reads as its own name.
Event types and next-step kinds
Action link helpers
Avault, store_login or approval link is a step the shopper takes outside the chat. Each step ends with a shopper message, and these helpers say which message ends which link.
A
vault or approval link opens on any https: host, since a company’s own Vault domain carries them too.
actionLinkOutcome returns one of completed, declined, failed or expired. An approval is completed once the shopper approved, even when the order then failed or the payment was refused, because the approval page has nothing more to do.
The function returns null for a reminder such as card_link_unfinished or approval_expiring. actionLinkOutcome also returns null when the message’s facts name another link of the same kind (facts.approvalUrl or facts.cardLinkUrl), or another store: a link that names its store stays open when facts.merchantName names a different one.
Action windows
actionWindows comes from @agent-cards/commerce-sdk/browser. The function opens each step in a pop-up window centered over the chat, so the shopper never leaves it, and closes the pop-up the moment the message that ends the step arrives. A phone’s browser opens the pop-up as a tab, and settle closes that tab the same way.
chat.ts
markStepDone, keepOfferingStep, stepLink, link and onShopperMessage stand for your own code. When the browser blocks the pop-up, open returns null and the link opens the way it would have, as a new tab.
Options
Methods
Call
open from the tap’s click handler. ActionWindow has id (the link’s actionLinkId), kind, url, store (string or null) and open (false once the window closed). open sets the pop-up’s opener to null as it opens, before its page loads, so the step’s page can neither move the chat’s page nor post to it. The chat keeps the window itself, so settle still closes the pop-up and onClosed still hears the shopper close it.
A browser finds no pop-up with no opener by its name. After a chat remounts, a tap on a step whose pop-up is still open opens a second window, and the first stays open until the shopper closes it.
open refuses every javascript:, data:, http: and relative address, and an https: address with a user name before its host. open refuses a local stack’s http://localhost links too, since the SDK has no development mode to allow them. The refusal throws ActionLinkRefusedError and opens nothing. console.log prints the following error, kind and reason for a Vault link on a local stack and for a store sign-in on another host:
The buy tool never hands over a link
open refuses, so a refusal means your code built or changed the link.