Skip to main content
Some steps of a purchase happen outside your chat. The shopper saves a card from the add-a-card link, signs in to DoorDash from the sign-in link, or declines the payment on the approval page. Agentcard tells your app the moment each one ends. If your app only posts Agentcard’s message, the shopper reads “Your Visa ending 4242 is saved, so you’re ready to check out.” and then has to type “ok” before anything moves. Take the next step for them instead, and the shopper reads one message that does the next thing: the approval link, the add-a-card link, or the total and a request for their yes.

Hear when a step ends

Three kinds of message end a step the shopper took outside the chat. Take the next step for these three, and post the message’s text as it is for every other kind, such as order_placed, whose text is already the whole message. A message whose advances is true is one of these three.
The messages arrive in onMessage, through listen or the webhook handler. NEXT_STEP_KINDS lists the three kinds that advance, and buy.nextStep(message) in the next section picks them out.

Confirm the yes they gave

Pick the next step by what the shopper said before they left the chat: A confirm sends the shopper’s yes for one exact cart, named by its hash: a short code that changes when anything in the cart changes. A cart that changed while the shopper was away is not paid, and the shopper is asked again. The approval page stays the shopper’s own consent: it names the most they can be charged, and Agentcard places the order only once they approve there. Never send words of your own as the shopper’s message on this step. Agentcard reads a shopper message as the shopper’s words, so text your app or your model wrote could read as a yes the shopper never gave.
Call buy.nextStep(message). It returns a turn, the buy tool for one run of your model, or null when there is no step to take. Run your model on the turn without awaiting it in the listener, and run one shopper’s turns in order.
server.ts
anthropic, histories, postToChat and textOf stand for your own code. turn.messages(history) ends with the event, marked as written by the system, and the instruction to take the next step in one short message. Post the model’s answer in place of message.text.The tool holds the shopper’s decision whatever the model calls. No call of the turn sends an ask to Agentcard. A confirm goes in only for the go-ahead the shopper already gave, once, for that cart’s hash. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard. A shopper message after the go-ahead that is not a plain go-ahead, such as “wait, make it two”, takes it back. A shopper who was not connected yet when they first asked gets that first ask run, in their own words, once their card is saved.After a pick, the model reads yes_carried with picked: true and never asks for the yes again. With direct: true and replyAsWritten: true, the turn’s call goes straight to Agentcard and turn.replyAsWritten is a fixed short line, so the turn needs no model call. Read the step lines lists the lines.

Answer a declined approval

An approval_declined message means the shopper said no to the payment. Nothing was charged, and the cart stays in the conversation. Send no confirm. Tell the shopper so, and offer a new approval:
On the shopper’s yes, confirm the cart’s current hash as a fresh yes. The answer carries a new approval link.
The turn from buy.nextStep writes this message for you.

Know what the shopper reads next

A total that moved because the store priced its fees and tax opens the line with the new total, such as it's $17.89 with fees and tax now. approve the payment to place your order (up to $19.02). Post this one message in place of the event’s text, so the shopper reads one message, not two.

Handle a message with no step

buy.nextStep returns null in four cases, and your code posts message.text then:
  • The message’s advances is false.
  • The message is for another shopper, or its link closed.
  • The tool already took a turn for the message.
  • The message arrives while a call for the shopper’s own message is still running. That call’s answer tells the model where the purchase stands.
When your agent cannot finish the turn, call step.release() before you post message.text, as the code above does. The text then reaches later turns once agentcard.delivered records it, and a redelivery of the event opens a turn again.The client keeps each message in memory, at most 20 for each shopper, so the listener and the turn run in one process on one client. When your model runs elsewhere, such as a serverless chat route, keep each message in your chat history as an assistant message, and the model reads it from there.

Check it before you go live

The sandbox, Agentcard’s test mode, sends no card_added, store_connected or approval_declined message, so test the follow-up with a message you send yourself, then once with live credentials.
  1. Pass a card_added message to your onMessage from a test of your own. Check that the chat posts one message that does the next thing, with nothing typed after it.
  2. Make your model throw during runModel. Check that the shopper still reads message.text.
  3. With live credentials, ask for a sandwich, pick one, answer the address, and save a card from the Vault link. Check that the next message is the approval link with no second request for your yes.