Stopping the sales agent without losing a single message

Friday evening: monthly usage is approaching the budget, and the website widget’s channel key shows up in the source of somebody else’s page. Both demand a quick response, and neither may leave customers writing into the void.

The agent’s controls are built so that stopping breaks nothing: the stop takes effect immediately, open conversations receive a closing message once, and incoming messages keep being recorded — just no longer answered by the model.

What this case requires

• A prepared closing message. Drafted only during the incident, it will be drafted badly; it can be stored in the controls or passed with the stop.
• A colleague who sees the recorded messages. Recording without an inbox merely moves the problem.
• A deployment that can update the widget script at once. The old channel key stops working immediately after rotation.
• Knowing which credential is affected. A targeted revocation hits only that one; a blanket one hits the whole channel.

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. Read the situation. GET /agent/usage returns, for one month, the billed amounts net of refunds, turns, colleague questions and conversations — in total, per channel and per day — plus balance and budgetState. That tells you whether the whole agent must stop or just one channel stands out.
2. Stop. POST /agent/stop optionally takes reason and closingMessage. The stop takes effect immediately; open conversations receive the closing message once so nobody waits without a word.
3. Keep recording. POST /agent/conversations/record creates a conversation in a colleague’s hands, stores the message and does not answer. That is the intended route for a stopped or capped account: nothing is lost and nothing is charged.
4. Rotate the channel key. POST /agent/channels/{channelId}/web-key/rotate issues the new webKey exactly once. The old one stops working immediately — so the new script tag belongs in the same deployment.
5. Revoke access selectively. POST /agent/channels/{channelId}/credentials/revoke with a purpose deletes exactly one credential — such as mail_smtp or ebay_refresh_token. Without purpose the whole channel is revoked, because a channel without its key would be silent and still active.
6. Resume. POST /agent/resume restarts operation; from the next message on, turns are answered again. Conversations recorded in the meantime stay with the colleague until they hand them back.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Monatsbudget erreicht","closingMessage":"Ein Kollege meldet sich persönlich bei Ihnen."}' \
  'https://api.tapinomahub.com/hub/index.php/agent/stop'

What you end up with

What remains is an incident in which no customer went unanswered, no key stayed valid longer than necessary and no message was lost. The agent is running again, and the interval is traceable in the inbox.

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.