Mobile app

Assist mode is FAQ + find products + change the cart. Checkout, address, and payment stay in the native Bag. Website widget and WhatsApp are separate channels.

What the shopper can do in chat:

• Ask store questions (hours, shipping, returns)
• Find products by text or photo
• Pick variants, see stock, add or remove lines
• Keep chat and the app Bag on one Odoo draft quotation
• Open native checkout when they are ready to pay
• List and track past orders

Base path: /api/v1/mobile/chat. Do not call Platform REST tools from the shopper app.

Two tokens

• MCP API key — workspace secret. Only your app backend uses it to create a session. Never ship it in the mobile binary.
• Customer JWT — returned by bootstrap. The client sends it on every chat request.

After login

Your backend already knows the shopper’s Odoo partner_id. Optionally pass the current draft sale order so chat and Bag stay on one quotation (odoo_cart_order_id).

curl -X POST https://YOUR_HOST/api/v1/mobile/chat/session \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_id": 42,
    "phone": "+919876543210",
    "odoo_cart_order_id": 156,
    "assist_mode": true
  }'

Response includes token, conversation_id, partner_id, odoo_cart_order_id, and current cart. Persist the order id in the app cart session and reload Bag if lines came back.

To resume the same thread later, send conversation_id on bootstrap. Keep assist_mode: true (default).

From the app, send text or a tap. Every reply is the same envelope: choose a screen from primary_type and render each item in assistant.widgets.

curl -X POST https://YOUR_HOST/api/v1/mobile/chat/messages \
  -H "Authorization: Bearer CUSTOMER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"show me office chairs"}'

Button taps:

{"type":"action","action_id":"add_catalog:1","action_label":"Add to cart"}

Always apply session after a reply:

• cart / cart_count — refresh the in-chat cart badge
• odoo_cart_order_id — write it back so Bag reloads the same draft
• navigate — if open_native_bag, open native checkout
• step — shopping | review | payment (coarse hint)

Widget types you will see:

• product_carousel — product cards
• option_list — variants, addresses, generic rows
• category_list — category chips
• cart_summary — lines + subtotal
• quick_actions — chips
• order_history / order_details
• navigate — open the native Bag

Show assistant.text as the bubble. Do not repeat it as a widget header. Product images may be /api/v1/mobile/chat/product-image?product_id=… — load them with the same host (no extra auth on GET).

Shoppers ask policy questions in natural language: opening hours, delivery areas, return window, payment methods, “do you have COD?”. There is no FAQ-specific endpoint.

1. Send { "type": "text", "text": "what is your return policy?" }.
2. Render assistant.text. Usually there are no widgets.
3. If they switch to shopping (“show me chairs”), continue on the same JWT and conversation.

Answers come from merchant-trained store knowledge (dashboard → eCommerce Agent setup → Store knowledge) plus the Odoo catalog. If the model is unsure, it will say so — do not invent a second FAQ UI.

Shoppers describe what they want. Chat searches the Odoo catalog and returns cards.

1. Send text, e.g. office chairs under 200 or show me sofas.
2. When primary_type is product_carousel, render a horizontal list from widgets[].items.
3. Each card: name, price (payable), optional strikethrough list_price, image, stock badge, and the actions the server sent. Do not invent extra buttons.
4. On tap, POST type: action with that action’s id and label.

Typical add button: add_catalog:{selection} (selection is the card index in that reply, not the Odoo product id). After add, expect cart_summary plus an updated session.cart.

{"type":"text","text":"show me office chairs"}

Same pipeline as text find: vision → catalog search → product_carousel. Requires image search enabled on the server (JPEG, PNG, WebP, GIF, max 10 MB).

JSON + base64 (typical native client)

curl -X POST https://YOUR_HOST/api/v1/mobile/chat/messages/image/json \
  -H "Authorization: Bearer CUSTOMER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "<base64 bytes>",
    "mime_type": "image/jpeg",
    "caption": "something like this"
  }'

Multipart

curl -X POST https://YOUR_HOST/api/v1/mobile/chat/messages/image \
  -H "Authorization: Bearer CUSTOMER_JWT" \
  -F "file=@chair.jpg" \
  -F "caption=looking for this chair"

1. Show a camera / gallery control in the composer.
2. Upload, then render the reply exactly like a text search (carousel + add to cart).
3. Optional caption narrows the search (“blue”, “kids size”).

Each carousel item may include:

• qty_available, in_stock, allow_out_of_stock_order
• can_order — in_stock || allow_out_of_stock_order

1. If can_order is false, show sold out and do not send add. The server already swaps the button to an out-of-stock label when needed.
2. Multi-variant templates use variant_pick:{template_id} (“Choose options”).
3. The next reply is option_list with purpose: "product_variants". Each row title is the attribute values; price is on the trailing edge. Tap variant_select:{product_id}.
4. Do not use the SKU as the primary label when attributes exist.

Chat writes the same draft sale.order the app uses for Bag when cart sync is on. If Odoo has sale.order.is_app, that app draft is preferred.

1. At bootstrap, send odoo_cart_order_id if the shopper already has a Bag.
2. After add / remove / clear, persist session.odoo_cart_order_id and reload Bag from Odoo. Chat lines and Bag lines stay one quotation.
3. Show cart in chat from cart_summary or session.cart.

Shoppers can also type or tap:

• View: text cart or action view_cart
• Remove: remove_cart:{product_id} or “remove the chair”
• Clear: action clear_cart or “empty my cart”

If bootstrap omitted the order id, still write back whatever odoo_cart_order_id the first add creates so later Bag opens are not empty.

With assist_mode: true, chat never places the order or collects payment. Checkout language (“checkout”, “place the order”, “buy this”, “open bag”) and the checkout_cart action all return the same signal.

1. Look for session.navigate === "open_native_bag" and/or a navigate widget with action: "open_native_bag".
2. Open the native Bag / checkout screen. Address and pay stay in the app.
3. You may also receive a quick-action chip open_native_bag — treat it the same (local navigation, not another chat call unless you want the copy again).

Ignore order_review / payment_link for assist-mode shoppers. Those widgets are for WhatsApp and website chat, not the native Bag path.

Shoppers can ask “where is my order?”, “my orders”, or tap history chips.

1. List: text or action my_orders → widget order_history.
2. Detail: tap track_order:{order_name} (e.g. track_order:S00063) → order_details.
3. Render one card: order name + date, status pills (tone: success / warning / danger / neutral), lines, totals, delivery block. Refresh uses the same track_order: id.
4. Assist mode still does not take payment in chat. If payment_url is present on a leftover unpaid order, opening it is optional; prefer the native order screen.

“Show categories” or action browse_categories returns category_list. browse_products returns a general catalog carousel.

1. Render chips from the list widget.
2. On tap, send the action id the server provided (category select ids are opaque — do not parse them).
3. The next reply is a product carousel for that category.

Always POST the id from the widget. This table is the contract so you can wire navigation and disabled states.

Probe GET /api/v1/mobile/chat/config for image_search_enabled and odoo_cart_sync if you need to hide the camera control or Bag badge.