Skip to main content

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: true while the conversation is open, false once 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 auto and the automation receives the message.
  • Without one, the session starts as queued and waits for an operator.
When the tenant opens the conversation through Session Start, the request chooses the type with sessionType, and Talqui falls back to the queue when the choice cannot be honored:
  • auto without an automation installed becomes queued.
  • manual without an operatorID becomes queued.
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 with 403 PERMISSION_DENIED.
Operator tokens are also accepted (it is what the Talqui app uses), but they act as a person and are not meant for integrations. Except for /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" }.
  • queued sends the conversation to the queue of human operators. It only applies when the session is auto: a session that is already queued or manual (an operator owns it) is left as it is, and the call still answers 200 with the unchanged session. The queue never takes a conversation away from an operator.
  • auto gives the conversation back to the automation. The current operatorID is not cleared.
  • manual sets 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, queue or operators), not what was asked.
  • operatorID: the operator this call put on the session, or null.
  • 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 (keep on an auto session nobody owns) or inbox-not-found.
  • fallbackApplied: true when fallback: "queue" sent the session to the queue.
  • selection: with several operatorIDs, the strategy applied, 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.
Errors of every endpoint on this page share one shape:

Closing

A closed session has sessionActive: 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, otherwise auto or queued as 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.
Full reference: Publish session typing.

When to call it

Call start 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.
Operator tokens are refused with 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 omit messageID, 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 in fields[0].allowed so you can retry.
On WhatsApp the typing indicator also marks the contact’s message as read, together with every message before it. Anchoring it to the right message is what keeps the contact from seeing “read” on a message nobody is answering.

Response

The endpoint answers 202 Accepted: the indicator reaches the channel asynchronously.
  • messageID: the contact message the indicator was attached to.
  • hasExternalID: false when that message has no identifier on the channel. Only the Talqui app shows the indicator then.
  • published: false with reason: "throttled": see below.

Throttling

Talqui publishes one start 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.

Behaviour by channel

Errors

Every status and error code of the endpoint is listed in the API reference. The indicator is cosmetic: if a call fails, carry on and send the reply.

References