B1Chat help and setup guide

This guide explains how administrators configure B1Chat and how users get access to the chat app. You do not need to understand B1Chat's internal user records, JSON mappings, or SAP payloads to complete the normal setup.

Simple rule: use Clients for mobile/chat access, and use Users only when someone also needs to sign in to the B1Chat web portal.

General setup (Administrator)

1. Open General Settings and configure the SAP Business One Service Layer connection.
2. Use General synchronization in General Settings for Items & barcodes (Full/Delta), synchronized stock, and the SAP supplier/BP master used by Document Extraction.
3. Run a Full sync once so B1Chat can load the SAP catalog and lookup information. Use Delta sync afterwards for normal updates.
4. Open the settings page for each module you want to use and enable it: Orders, Transfers, Document Intelligence, and Document Extraction.
5. Register the customers, warehouses and mobile numbers that are allowed to use B1Chat from Clients.

Contextual help beside settings

Portal configuration pages show a small i icon beside each setting label. Click it to get help for that exact field without leaving the page.

• The first explanation is local-first and uses the B1Chat Help knowledge whenever it can answer deterministically.
• Use Example, ask a follow-up, or use Improve current text for non-secret text fields. When synthesis is needed, Help uses the cloud model assigned to that customer by Platform Admin and records normal Help AI usage.
• Password, API-key, token and credential fields are protected: B1Chat does not read or send their current value to Help AI. Never paste a secret into the Help chat manually.
• The same helper also appears on dynamic Business Vocabulary, Conversation Rule and External Tool rows added after the page loads.

Customer-specific chat intelligence (Tenant Administrator)

Open Chat & AI Settings to teach B1Chat how this customer's business works. These settings belong only to the current customer.

• Business vocabulary maps terms such as Brand, Family or Make to this customer's SAP Item Group, Manufacturer or an Item UDF. A request such as list brands is then resolved as a business dimension instead of a normal product-name search.
• Conversation rules define when more information is required. For automotive spare parts you can ask for VIN first and accept brand/model/year/engine as the alternative. B1Chat remembers the captured context for later part requests in the same conversation.
• External tools / portals connect approved HTTP APIs such as VIN lookup, parts catalogue, supplier stock or technical data. Each tool has its own encrypted credential. Credentials stay on the B1Chat server and are never sent to OpenAI or Claude.

Automotive starter: the one-click starter adds brand → SAP Item Group for this customer and a VIN-first spare-parts clarification rule. Review it before saving and attach the customer's VIN/parts tools if required.

Authenticated external tools require HTTPS. The generic connector supports GET/POST APIs with Bearer token, API-key header or Basic authentication. Browser-only portals that have no callable HTTP/API contract require a dedicated provider adapter rather than exposing website credentials to the AI.

AI provider/model agreement: tenant administrators cannot select the cloud provider or paid AI models. Platform Admin assigns those per customer in Platform Settings. The tenant can still maintain its own business rules and its own provider API credentials where applicable.

Language: B1Chat uses automatic language detection. There is no Greek/English/customer language mode. Voice transcription keeps the detected spoken language, mixed-language messages are allowed, and tenant vocabulary/rule aliases can be entered in any language.

Modules and licensing

• Orders - lets an authorized customer search products, check stock, build a cart, review totals and create sales orders through B1Chat.
• Warehouse Transfers - lets an authorized warehouse user work with warehouse-transfer requests and transfers according to your configured transfer rules.
• Document Intelligence - validates submitted document packs against the configured pack templates and rules.
• Document Extraction - reads supplier PDFs/images, lets the user review the extracted data, and creates the configured SAP purchasing document.

A module must be enabled for the tenant and also authorized for the individual mobile/user. B1Chat only shows and accepts actions that the current user is authorized to use.

Mobile permissions and chat features (Administrator)

When you add or edit a mobile from Clients, select which capabilities that person may use:

• Orders
• Warehouse transfers
• Document Intelligence
• Document Extraction
• Image chat - allows the user to send product/document images where supported.
• Speech chat - allows the user to send voice messages.

Text chat is always available, so there is no separate text-chat permission.

These permissions are enforced by the server as well as by the user interface. Hiding a button is not the security control.

Activate the B1Chat mobile app

1. First register the person's mobile under the appropriate customer and/or warehouse in Clients.
2. Use the QR action to display an activation QR code, then let the user scan it from the B1Chat mobile app.
3. Alternatively use the SMS action to send the activation information to the registered mobile number.
4. After activation, the mobile app loads the permissions assigned to that mobile and only exposes the authorized B1Chat modules/features.

A normal mobile-chat user does not need a web-portal username or password. The registered mobile is their app identity.

Clients versus Users

Clients = mobile/chat access. Use Clients to connect a mobile number to an SAP customer or warehouse, authorize modules, allow Image/Speech chat, and activate the B1Chat mobile app by QR or SMS.

Users = web-portal access. Use Users only for staff or other people who need to log in to the B1Chat web portal with an email and password.

If the same person needs both mobile chat and portal access, enter the same mobile number when creating portal access. B1Chat reuses the same internal identity automatically; administrators do not need to merge duplicate users manually.

Internally B1Chat keeps identity, customer/warehouse assignments, credentials and permissions separate. This gives one person a consistent identity without making administrators manage those technical records.

Portal access (Administrator)

Open Users when somebody needs access to the B1Chat web portal.

1. Enter display name, email, mobile number and a temporary password.
2. Select User or Administrator.
3. For a standard portal user, select the modules they are allowed to access.
4. Create the portal access and give the credentials to the user securely.

Portal credentials are separate from mobile activation. Adding portal access is optional for normal B1Chat mobile users.

Testing access

Use Chat from the portal to test the modules allowed for the signed-in portal user. For mobile users, activate the app by QR/SMS and confirm that only the expected module buttons and media capabilities are available.

If a module is missing, check both levels: the module must be enabled in tenant settings and the user's mobile/portal identity must have permission for it.

Chat attachments are one at a time: when a user selects a photo or document, or finishes a voice recording, B1Chat sends it immediately. There is no separate attachment queue in the chat composer and no need to press Send again.

MAUI Document Extraction: tapping Document Extraction offers Take photo or Choose existing document. The selected/captured PDF or image is submitted immediately.

Product selection: a single exact product match uses the same quantity row as a multi-product result, so the shopper enters quantity and accepts it directly in the list. Cart/basket totals update immediately after the add action; opening the Cart is not required to refresh the count.

Product lists: after entering a quantity and tapping the accept/check button, B1Chat updates the result/cart at the bottom but keeps the current list position so the user can continue selecting more products without being moved to the newest message.

Sales Orders clients and mobile access (Administrator)

1. Open Sales Orders > Clients.
2. Type all or part of the customer's CardCode, name, telephone or cellular number. You can also click the find button in the customer field.
3. B1Chat searches SAP Business Partners using CardCode, CardName, Tel1, Tel2 and Cellular. If more than one customer matches, use the paginated customer-selection window and its filter to select the correct customer.
4. Register the customer, then choose Edit to manage the mobile numbers allowed to use B1Chat for that customer.

The Clients screen is intentionally based on SAP customers and mobile numbers. You do not need to create a username just to use the mobile chatting app.

Check product stock in chat

Users can ask stock questions naturally, for example “do you have stock for chivas”, “is chivas available”, or “do you have 5 pcs chivas 70cl”.

• B1Chat treats the request as a read-only stock enquiry and removes stock-question wording before matching the product.
• If several genuine variants match, B1Chat shows stock for those variants instead of opening add-to-cart quantity controls immediately.
• Numbers such as 70cl or 500ml remain product attributes. A number is treated as requested quantity only when the wording makes quantity explicit.
• After reviewing stock, the user can name the item code or size to continue ordering that variant.

Warehouse Transfer clients and mobile access (Administrator)

1. Open Transfers > Clients.
2. Select the SAP warehouse and register it.
3. Choose Edit beside the registered warehouse and add the mobile number(s) allowed to work with that warehouse.
4. Set the required module and media permissions for each mobile.

The same mobile can be assigned to both a customer and a warehouse. Its existing permissions are reused so adding another assignment does not silently remove access already granted elsewhere.

Document Intelligence setup and use

1. Open Document Intelligence Settings and set the minimum confidence, retention period and any tenant validation instructions.
2. Open Document Packs to maintain providers and pack templates.
3. Use Teach from reference files when you have representative PDFs/images and want B1Chat to propose the expected documents, rules or required photos. Review the proposal before publishing it.
4. In each pack template, define expected documents, validation rules, required photos, validity dates and pack-level instructions. Publish only after testing representative submissions.
5. Grant the Document Intelligence permission to the required mobile/portal identities. The server enforces this permission as well as the UI.
6. Users submit the requested documents/photos from chat; B1Chat validates the pack against the published template and returns review/decision information without exposing the underlying JSON mappings.

Document Intelligence validates a set of documents against a pack template. Document Extraction is a separate module that reads supplier documents and builds SAP purchasing documents.

Document Extraction settings (Administrator)

1. Open Document Extraction - Settings and enable Document Extraction.
2. Choose what a reviewed supplier document should become in SAP: A/P Invoice, Goods Receipt PO, Purchase Order, or Goods Return Request.
3. Choose whether SAP documents should initially be saved as drafts.
4. For A/P Invoice or Goods Receipt PO, enable Match lines to open Purchase Orders (FIFO) if you want B1Chat to base extracted lines on open purchase-order lines.
5. Optionally enable Auto send to SAP when fully matched. Leave it off while testing new Supplier Layouts. When enabled, B1Chat posts only after all mandatory SAP item/G/L lines resolve and the normal send validation succeeds; documents that are not fully ready stay in Review.
6. Save the settings and use Queue to upload supplier documents.

Purchase Order / Goods Return Request targets: B1Chat disables its open-Purchase-Order FIFO base matching for these standalone targets. If an extracted supplier document is a Credit Note or explicit Return document (for example Credit Return, Goods Return or Purchase Return) while the configured target is Purchase Order, Review automatically switches the SAP target to Goods Return Request. Credit Invoice remains an invoice. Other unsupported credit/return target combinations remain blocked rather than posting the wrong SAP document.

Credit Invoice wording: supplier headings such as Credit Invoice or Credit Sales Invoice remain invoices. Only explicit Credit Note/Credit Memo classification enters the credit workflow; a matched Supplier Layout and its Document type heading are preferred over loose keyword guessing.

Parallel processing: B1Chat already serves different chat sessions concurrently. Document Extraction uses a bounded background worker pool (default 2 workers) so more than one queued supplier document can progress at once. The platform setting Processing:DocumentExtractionWorkers can be increased only after measuring cloud-provider rate limits, SAP Service Layer capacity and end-to-end queue throughput.

Cloud extraction: B1Chat uses the OpenAI or Claude provider/model assigned to that customer by Platform Admin for AI work. Published tenant Supplier Layouts are resolved first, then published Platform Predefined Layouts, before generic cloud extraction is used. There is no Local/Cloud routing choice in the tenant portal.

AI cost visibility: successful cloud-AI calls record the provider, model and provider-reported input/output token usage in the billing ledger. B1Chat snapshots the configured/list token rates at the time of the call and shows an estimated AI cost in Platform Billing. This is an operational estimate, not the provider's invoice; custom or unknown models remain visible with their tokens and are marked unpriced until a rate is configured.

Create a Supplier Layout visually (Administrator)

Use Document Extraction - Supplier layouts. The layout designer is visual; normal users never need to edit fingerprints or field-mapping JSON.

1. Select the Supplier and the document type, such as Invoice or Credit Note.
2. Give the layout a clear name.
3. Upload a representative supplier PDF or image as the reference document.
4. Select the required field from Field.
5. For a value printed on the supplier document, keep Read from document and drag a rectangle directly over the matching field or column. To correct it later, click the rectangle, drag it to move it, or drag one of its edge/corner handles to resize it.
6. For a constant value that is not printed on the document, choose Use fixed value, enter the value and add it. This is useful for defaults such as SAP warehouse, VAT/Tax code, Project code, Cost Center / Distribution Rule 1-5, G/L Account, and SAP document type.
7. Repeat this for the header, line columns and totals. The document canvas scrolls while the mapping layer continues over the full page, so totals at the bottom can be selected normally.
8. Save draft while testing or adjusting rectangles, then Publish the layout when it is ready. Live queued extraction uses published layouts; a draft is not selected automatically.

Item vs service documents: add the Header field SAP document type (Items / Service) to a Supplier Layout. A fixed value of dDocument_Items creates normal item documents. A fixed value of dDocument_Service is accepted only when a Supplier Layout is positively matched; generic extraction is always itemized. For service layouts, choose either Single G/L account (one service line for Document Total minus VAT/Tax) or Map supplier lines to G/L accounts (supplier item/catalogue/barcode/manufacturer values map deterministically to SAP G/L accounts).

Use rectangles to teach B1Chat where information appears. The line-table rectangle is also used for a focused server-side crop during recovery, so the vision model sees the configured table at higher relevance instead of relying only on whole-page guessing. Use fixed values only for real supplier/layout defaults that should always be sent the same way. Use Special instructions only for exceptional rules that cannot be represented clearly by rectangles or defaults.

Editing later: new/updated layouts keep their tenant-scoped reference PDF/image so clicking Edit reopens the same document automatically. Layouts created before this feature did not retain the reference file; select that PDF/image once and save the draft to attach it for future edits.

What to mark on a supplier document

Mark the areas that make the supplier document unambiguous and that B1Chat needs to extract correctly. Typical examples are:

• Supplier identity - B1Chat first uses VAT/tax number, supplier name/aliases and strong published Supplier Layout/Platform template identity. Only if those methods leave the supplier unresolved may exact BP catalogue numbers be used as a final SAP AlternateCatNum fallback. A single catalogue number must be corroborated by an independent exact item identifier; otherwise at least two distinct catalogue numbers must agree on the same supplier.
• Document type - the printed wording that identifies Invoice, Credit Note, Delivery Note, etc.
• Header fields - document number, document date, currency and other required header values.
• Line fields - ItemCode, supplier code, barcode, description, quantity, UoM, unit price, discount %, tax/VAT code, line total, Warehouse, Project, Cost Center / Distribution Rules and G/L Account as applicable. These fields are in one list and each can be read from the document or assigned a fixed value.
• Totals - subtotal/net total, VAT/tax total, discount/freight where applicable, and document total.

For repeating lines, draw the rectangle over the printed column heading or a representative first-row value/column area and assign what that column means. The saved technical mapping is generated by B1Chat.

Line recovery: when a mapped line table is tall, B1Chat automatically processes it in smaller overlapping visual segments. This improves cloud vision reliability and prevents one very large table request from deciding the whole result. If a provider returns damaged outer JSON but a valid lines[] array, B1Chat salvages that array without inventing values.

How to verify the layout was used: open the extracted document in Review. The summary shows Layout: name vN when a published supplier layout was selected, or Generic extraction when no layout matched. After publishing or revising a layout, use Re-extract so the source is processed with the current published version.

Maintain configured Supplier Layouts

The Configured layouts table in Supplier layouts shows the layouts available for extraction.

If a layout is no longer required, use its Delete action. B1Chat removes it when safe. If historical extraction/audit records already reference the layout, B1Chat archives it instead so historical evidence is not broken.

Upload, review and send an extracted supplier document

1. Open Document Extraction - Queue.
2. Select a supplier PDF/image and click Queue document. The upload is queued immediately so you can submit another document without waiting for extraction to finish.
3. Watch the queue status. Open the result when it is ready for review.
4. When you Remove an extraction from the queue, B1Chat also attempts to delete that run's stored source/rendered folders immediately to reclaim disk space. The structured SQL/SAP audit remains; if Windows temporarily locks a file, retention cleanup can retry later.
5. Use View source document whenever you need to compare the extracted values with the original attachment.
6. Verify the supplier, document number/date, target SAP document, currency and every mapped/fixed layout field shown in Review. Review is the editable source of truth used to build the SAP payload.
7. For Supplier Layouts, Review is strict: only fields selected or fixed in that layout are shown/used. Unmapped AI fields are ignored. The header Reference (NumAtCard) maps to SAP NumAtCard; Line Net amount is not a selectable layout field because Line Total amount is the supported row amount.
8. Use Refresh SAP matches after correcting SAP product/barcode master data or a reviewed line. B1Chat first completes a product delta sync (including the local matching index), then reruns only deterministic SAP matching; it does not rerun OCR/AI extraction.
9. If an extracted line remains unresolved, use the Find magnifier beside the mandatory SAP ItemCode field. Search the synchronized SAP catalogue by ItemCode, description, barcode, or manufacturer catalogue number, then select the correct item without rerunning extraction.
10. Save the review, then use Send to SAP when the document is correct. Administrators can optionally enable Auto send to SAP when fully matched; in that mode a newly queued document is posted automatically only when every required line is resolved and normal SAP-send validation passes. Otherwise it stays in Review.

The original supplier file remains associated with the extraction so reviewers can inspect the source while approving the SAP document. Discount %, fixed defaults and other mapped values shown in Review are posted from the saved Review when they contain a value.

Document total posting: when extraction or a Supplier Layout provides a reviewed Document total, B1Chat sends that value to SAP as DocTotal. B1Chat does not derive or send a header DiscountPercent from Subtotal, Discount or VAT totals; line discounts remain on their individual SAP rows and SAP Business One performs the document-level calculation from the requested DocTotal.

Mapped numeric accuracy: for published Supplier Layouts, missing mapped numeric totals are re-read from their exact configured rectangle using a focused local-first vision crop. B1Chat also cross-checks mapped line Quantity, Unit price, Discount % and line amount arithmetically and corrects only a single unambiguous inconsistent numeric cell (for example a scanned 14 misread as 1 or 27% misread as 25%). It does not invent values when more than one correction is possible.

Preprinted unused rows: when a Supplier Layout maps Quantity from the document, B1Chat treats blank/zero-quantity template rows as unused and does not show or post them. If a positive mapped Line Total exists while Quantity is unreadable, the row is kept for Review rather than silently discarded.

Handwritten decimals: handwritten accounting numbers are interpreted differently from printed locale conventions. A single comma or dot in a handwritten numeric value is treated as the decimal separator (for example handwritten 1,250 or 1.250 means 1.250), because thousands grouping is unusual in handwriting. The original separator is still preserved in extraction evidence/diagnostics.

Support diagnostics: open a Queue item and use Export diagnostics to download a JSON file containing the exact saved Supplier Layout identification/mapping/instructions, structured extraction, Review values, validation and SAP payload/result metadata for that run. The original PDF/image is not embedded; send it separately when escalating recognition issues.

API access for custom integrations (Technical/integration use)

This section is only for developers integrating another site/app directly with B1Chat. Normal mobile and portal users do not need an API key.

Every API request needs the tenant API key in an X-Api-Key header. sessionId is a unique value generated by the calling application to keep conversations separate.

const form = new FormData();
form.append('sessionId', mySessionId);
form.append('text', 'do you have green tea?');

const res = await fetch('https://your-b1chat-server/api/chat/message', {
  method: 'POST',
  headers: { 'X-Api-Key': 'b1c_your_key_here' },
  body: form
});
const reply = await res.json();

Images and voice notes use the same request with an image or audio file field where that tenant/user is authorized for the corresponding media feature.