Overview
Every conversation in Talqui is a Session. Along its life a session moves between owners: an automation (a chatbot or an AI agent), the queue of human operators, one specific operator, and finally the history of closed conversations. Knowing these states tells your integration what is happening in a conversation and what it is allowed to do there. Two fields describe the state:sessionActive:truewhile the conversation is open,falseonce it is closed.sessionType: who owns an open conversation.
Other fields record the timeline:
queuedAt (first time it entered the queue), manualAt (first time an operator took it), closedAt and closeMotive (when and why it ended).
How a session is born
A session starts in one of two ways: the contact writes to the tenant, or the tenant opens the conversation (an operator, a campaign, or your backend through Session Start). When the contact writes, the first type depends on whether the tenant has an automation installed. Talqui looks for an enabled connection of a chatbot plugin (the Talqui chatbot, AI agents, or a third-party chatbot plugin):- With an automation, the session starts as
autoand the automation receives the message. - Without one, the session starts as
queuedand waits for an operator.
sessionType, and Talqui falls back to the queue when the choice cannot be honored:
autowithout an automation installed becomesqueued.manualwithout anoperatorIDbecomesqueued.
A session that enters the queue may leave it right away. When the tenant has distribution rules turned on, Talqui picks an operator as soon as the session is queued, and it becomes
manual in the same step.Session states
A session goes through two layers of state. The first is its lifecycle: it is open, then closed, and may wait for a rating on the way out.Moving between owners
While the session is open,sessionType tells who owns it, and ownership moves as the conversation progresses.
A request to move a conversation to the queue only applies when it is
auto. A conversation that an operator already owns is never pulled back to the queue by that request.
Changing the owner through the API
Your backend can move a conversation between owners and inboxes with these endpoints of the REST API (https://api.talqui.chat):
They accept these credentials (see the Authentication guide for how to build each header):
- An API credential access token (
Authorization: Bearer <ACCESS_TOKEN>) of the same tenant. This is the path for integrations. Plugin: your plugin’s own credential, accepted only when the plugin is installed in that tenant.PluginConnection: the connection of your plugin in that tenant, on every endpoint except/transfer, which refuses it with403 PERMISSION_DENIED.
/inbox, they act on open sessions only: a closed or unknown session answers 404 SESSION_NOT_FOUND. On success /type, /routing and /inbox answer 200 with the session as it was left, in data.session.
Change the type
Body:{ "sessionType": "auto" | "queued" | "manual" }.
queuedsends the conversation to the queue of human operators. It only applies when the session isauto: a session that is alreadyqueuedormanual(an operator owns it) is left as it is, and the call still answers200with the unchanged session. The queue never takes a conversation away from an operator.autogives the conversation back to the automation. The currentoperatorIDis not cleared.manualsets the type only and does not assign an operator. To hand the conversation to someone, use the routing endpoint below.
Assign to an operator
Body:{ "operatorID": "<OPERATOR_ID>" }. The session is assigned to that operator and becomes manual, whatever its type was. Assigning it to the operator who already owns it changes nothing.
The operator must be able to take the conversation, otherwise the session is left untouched and the call is refused:
Transfer
POST .../transfer does an inbox move and a distribution in one call, in this order: it moves the session to inboxID, then distributes it, then applies fallback if the session is still unrouted. Every body field is optional.
An operator who cannot take the session, or an inbox that cannot be used, is not an error: the call answers
200 and tells what happened.
distribution: what happened (keep,queueoroperators), not what was asked.operatorID: the operator this call put on the session, ornull.inboxChanged,previousInboxID: whether the session changed inbox, and the inbox it was in before.inboxNotFound: the requested inbox does not exist, was deleted or is archived. The session stays in its inbox.fallbackReason: why the distribution did not assign anyone:operator-not-found(the single operator is not a member of the tenant),operator-no-inbox-access(they cannot reach the session’s inbox),no-operator-available(nobody in the pool could take it),keep-not-routed(keepon anautosession nobody owns) orinbox-not-found.fallbackApplied:truewhenfallback: "queue"sent the session to the queue.selection: with severaloperatorIDs, thestrategyapplied, why that operator was picked, the pool size and how many of them were online or away.
Move to another inbox
Body:{ "inboxID": "<INBOX_ID>" } moves the session to that inbox; { "inboxID": null } takes it out of its inbox. The field is required. This endpoint also works on closed sessions.
The owner does not change, with one exception: an operator who has no access to the destination inbox is removed from the session, which goes back to the queue there (where the inbox’s automatic routing may assign it). Moving a session to the inbox it is already in changes nothing.
An API credential and a Plugin credential act on behalf of the tenant, with a manager’s access. A PluginConnection acts with an operator’s access: it cannot take a session out of its inbox when the tenant hides the all conversations inbox.
Closing
A closed session hassessionActive: false, closedAt set, its owner cleared (operatorID: null) and sessionType reset to auto. The closeMotive field tells why it ended. Common values:
After a session is closed, the next message from the contact opens a new session, with two exceptions:
- Waiting for a rating. When the conversation is closed asking for a satisfaction rating (CSAT), it stays closed but waits for the answer. While the tenant’s rating window is open, the contact’s next message is read as the rating and belongs to the closed session. The cycle ends when the contact answers or the window expires.
- Reopen window. A tenant can turn on a short reopen window (15 minutes by default, off for new tenants). A contact who writes again inside it, typically a “thanks!” right after the operator closed, reopens the same session: back to the same operator (
manual) when an operator was talking to them, otherwiseautoorqueuedas for a new conversation.
Closing through the API
PATCH https://api.talqui.chat/tenants/{tenantID}/sessions/{sessionID}/close closes a session. It accepts an API credential, PluginConnection, Plugin and operator tokens.
A close by an API credential or a plugin is not counted as a close by an operator: no operator is recorded as having closed it by hand. The rest is the same as any close: the session leaves the open conversations, the tenant’s closing message is sent when one is set up, and the conversation goes to the history.
An unknown or already closed session answers
404 SESSION_NOT_FOUND. The exception is a session closed by inactivity that is still listed among the open conversations: the call only removes it from that list. On success the answer is 200 with the closed session in data.session.
Typing indicator
A plugin that takes a while to answer, such as an AI agent calling a model or an integration looking up an order, can show the contact that a reply is on its way. Talqui shows the indicator in the conversation inside the Talqui app and, where the channel supports it, to the contact.When to call it
Callstart as soon as your plugin receives the contact’s message, then send the reply as usual. There is no need to call stop after replying: the indicator ends when the reply arrives.
Authentication
The endpoint accepts machine credentials only. See the Authentication guide for how to build each header.PluginConnection: the connection of your plugin in that tenant.Plugin: your plugin’s own credential, accepted only when the plugin is installed in that tenant.
403. The indicator is published on behalf of an automation, never of a person.
Request
The reference message
The indicator is always attached to the latest message the contact sent in the session. When you omitmessageID, Talqui finds that message for you, and this is the recommended way to call the endpoint.
When you send messageID, it must be exactly that message. Otherwise the call is refused:
- a message of another session answers
404 TypingMessageNotFoundError; - a message sent by the tenant answers
409 TypingMessageNotInboundError; - an older contact message answers
409 TypingMessageNotLatestError, with the latest message infields[0].allowedso you can retry.
Response
The endpoint answers202 Accepted: the indicator reaches the channel asynchronously.
messageID: the contact message the indicator was attached to.hasExternalID:falsewhen that message has no identifier on the channel. Only the Talqui app shows the indicator then.published: falsewithreason: "throttled": see below.
Throttling
Talqui publishes onestart per session every 5 seconds. Extra calls inside that window answer 202 with "published": false, "reason": "throttled"; they are not errors and need no retry. A stop frees the window, so the next start goes out right away.