When a colleague takes the conversation over

A customer writes that the delivered control unit is coded and does not fit. This is not a standard case: it concerns warranty, a return and possibly goodwill. The agent recognised that and flagged the conversation as worth handing over. Now the organisation decides, not the technology.

Takeover and release are explicit moves, not a side effect. The reason is simple: the actual damage does not arise when an agent does not know something but when agent and human answer at the same time. That is why every conversation carries exactly one owner at all times.

What this case requires

• A surface for colleagues. The inbox can be opened through a browser session so that not every employee needs an API key.
• A responsibility rule in the team. Whoever takes over must also hand back; otherwise the agent stays permanently silent on that conversation.
• A look at the counters. What nobody reads is not an inbox but an archive.
• A decision about price offers. Offers can be listed separately — whoever does not look at them is not negotiating but waiting.

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. Survey the inbox. GET /agent/inbox/summary returns the counters. The advantage over a list is the decision before loading: you see whether anything is waiting at all before fetching forty conversations.
2. Filter the conversations. GET /agent/inbox/conversations knows needsHuman, owner, unread, channelType and the search term q over subject and preview, plus nextCursor. For a work queue needsHuman is the most important filter — it shows exactly what the agent handed over itself.
3. Take the conversation over. POST /agent/inbox/conversations/{conversationId}/takeover sets the owner to the colleague. From here the agent no longer answers here. The changed field says whether the takeover actually took effect or whether somebody else was faster.
4. Ask the agent for help. POST /agent/inbox/conversations/{conversationId}/assist returns answer and suggestedReply, plus findings. That is the difference from a turn: the suggestion goes to the colleague, not to the customer. Sending stays manual.
5. Reply by hand. POST /agent/inbox/conversations/{conversationId}/reply sends the text and answers with deliveryStatus. According to the contract, on a mailbox or marketplace channel the reply is queued for delivery, and on the website it counts as delivered at once; the contract does not define the individual values of deliveryStatus.
6. Hand back. POST /agent/inbox/conversations/{conversationId}/release returns the conversation to the agent. Without this step a conversation once taken over stays manual forever — the most common reason automation peters out in daily practice.

curl -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/hub/index.php/agent/inbox/conversations?needsHuman=true&limit=25'

What you end up with

What remains is a conversation whose ownership was unambiguous at every moment, and a team that only handles the cases which genuinely need a human. The agent stays responsible for everything else.

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.