The sales agent answers in the widget on your own website

Many enquiries about a used part are the same three questions: does it fit my vehicle, what does shipping cost, what condition is it in. They arrive in the evening and at weekends, and whoever waits until Monday buys elsewhere. A form captures the question but does not answer it.

The website channel is built as a browser gateway, not as a Hub call with a hidden credential: the widget authenticates with a channel key that can be rotated at any time. Your API key stays on the server, where it belongs.

What this case requires

• A configured profile. The agent answers according to its instruction; without a profile there is no tone, no rules and no permissions.
• A website channel with allowed origins. allowedOrigins defines which addresses the widget may speak from — that is the protection against misuse of the channel key. When setting up the widget and when starting a conversation, the Origin of the request must be one of these origins; otherwise the gateway answers with origin_not_allowed.
• The visitor token. GET /web/channel issues it; the gateway expects it back in the X-Agent-Visitor header.
• Somewhere for handovers to land. needsHuman without an inbox is a warning nobody reads.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Set up the widget. GET /web/channel returns title, greeting, accentColor, locale, pollIntervalSeconds and maxMessageChars. The surface is therefore not hard-wired in the script but loaded from the channel — changing the greeting needs no new page build.
2. Start the conversation. POST /web/conversations accepts the first message and immediately performs the first turn. Back come conversationId, seq and the reply, plus needsHuman and owner. A second call for the first reply would be avoidable waiting.
3. Keep answering. POST /web/conversations/{conversationId}/messages performs every further turn. The clientMessageId matters more than it looks: if a message is sent again with the same clientMessageId, the call returns the stored reply instead of running again.
4. Close the conversation. POST /web/conversations/{conversationId}/close ends it. Closed does not mean deleted — the history stays traceable in the inbox, and that is exactly what you need in a complaint.

curl -X POST \
  -H 'X-Agent-Channel-Key: <KANALSCHLUESSEL>' \
  -H 'X-Agent-Visitor: <BESUCHERTOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Passt der Scheinwerfer an einen Golf 7 Facelift?","clientMessageId":"m-1"}' \
  'https://api.tapinomahub.com/agent/api/index.php/web/conversations'

What you end up with

In the end the website answers the recurring questions itself and passes the rest, with their history, to a colleague. The visitor does not wait until Monday, and the colleague does not start from zero.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-agent). All use cases arranged by surface and role: overview of the use cases.