Flow Entry Point

Overview

By default, every conversation handled by the Chatbot Builder starts at the same place: the initial non-editable block at the top of the flow. That is the correct behavior for conversations started by the contact, because Talqui has no prior context about why the person is writing.

Conversations opened by your own system are different. When your application calls the Sessions endpoint to start a conversation, it already knows why that conversation exists — an order was delayed, an invoice is due, a delivery was rescheduled. In those cases, sending every contact through the same generic opening menu is wasteful, since your integration already has the information needed to pick the right path.

To support this, the Sessions endpoint accepts an optional entry point. Instead of starting the flow at the initial block, Talqui resumes the conversation at a specific sequence of your flow, which lets a single flow serve many different transactional scenarios with completely independent paths.

The entry point is declared through the sessionLastSmartID field of the Session Start request.

Sequences and Sequence IDs

In the Flow Builder canvas, blocks are not free-floating: they are grouped into sequences. A sequence is the card you see on the canvas, and the blocks inside it are executed from top to bottom before the flow follows the connection to the next sequence.

Every sequence has its own identifier, and that identifier is what your integration sends as the entry point.

To copy it:

1. Open the Chatbot flow in Talqui.
2. Click the sequence you want to reference, so it becomes selected.
3. Click the ⚡ action that appears on the sequence card.
4. Talqui copies the identifier to your clipboard and confirms with the message "ID da sequência copiado para a área de transferência".

The copied value is not a bare UUID. It is a prefixed identifier in the form subset-<uuid>:

subset-c673adab-2db3-4dcb-b72f-0015e1d9592c

Send the value exactly as copied, including the subset- prefix. The prefix is part of the identifier, so a value without it — or pointing to a sequence that no longer exists — cannot be resolved to any sequence of the flow.

The identifier is also stable: it does not change when you edit the blocks inside the sequence, rename messages, or move the card around the canvas. You can safely store it in your application configuration.

How the Entry Point Resolves

The entry point does not execute the blocks of the sequence you reference. Talqui uses the referenced sequence as an addressing marker and starts the conversation at the first block of the sequence connected to it.

sessionLastSmartID: <ID of sequence A>

   +-------------------+         +----------------------+
   |    Sequence A     | ------> |      Sequence B      |
   |   (referenced)    |         |  conversation starts |
   |   not executed    |         |  at the first block  |
   +-------------------+         +----------------------+

This is why the recommended design is to create a small, dedicated entry sequence for each scenario your integration needs to trigger. The entry sequence carries no blocks — its only job is to hold a stable identifier and point to the real path.

Any blocks placed inside the referenced sequence are ignored, so keeping it empty avoids confusion for whoever maintains the flow later.

Recommended Pattern: Entry Sequences

Create one empty entry sequence per scenario, connect each of them to the path that should handle that scenario, and store the identifiers in your application:

[Entry: Order Delayed]    ------>  [Order Delayed Path]
[Entry: Invoice Due]      ------>  [Invoice Due Path]
[Entry: Delivery Window]  ------>  [Delivery Window Path]

With this layout, your backend decides which conversation it is opening and sends the matching identifier. The flow stays readable in the builder, each path evolves independently, and the operations team can rewire a scenario by dragging a single connection without asking for a deploy on your side.

Requirements

For the entry point to be applied, all of the conditions below must hold:

• The tenant must have a chatbot installed, and the session must be created as auto. If the tenant has no automation available, Talqui falls back to queued and the entry point is not used. See the routing rules in the Session Start guide.
• The request must create a new session. If that contact already has an open conversation on the same channel and plugin connection, Talqui reuses the existing session and the entry point is ignored, because the conversation already has its own position in the flow.
• The referenced sequence must have exactly one outgoing connection. If it has none, there is no path to resume and nothing is executed. If it has more than one, the path that will be followed is not predictable.
• The sequence connected to it must contain at least one block. An empty target has nothing to execute.

When the Flow Runs

Declaring an entry point does not make the chatbot speak immediately. The first outbound message of the conversation is the one your request sends, exactly as in any other Session Start.

The entry point is consumed when the contact replies with a text message. At that moment, Talqui resumes the conversation at the configured position instead of the initial block, and the flow proceeds normally from there.

Example

The request below opens a conversation and tells Talqui to resume the flow at the path connected to the referenced sequence:

curl --request POST \
  --url https://api.talqui.chat/tenants/<TENANT_ID>/sessions \
  --header 'Authorization: PluginConnection <PLUGIN_CONNECTION_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "channel": "<CHANNEL_URN>",
    "pluginConnectionID": "<PLUGIN_CONNECTION_ID>",
    "contactExternalID": "<CONTACT_IDENTIFIER>",
    "messageKey": "text",
    "messageValue": "Your order #98213 was rescheduled",
    "sessionType": "auto",
    "sessionLastSmartID": "subset-c673adab-2db3-4dcb-b72f-0015e1d9592c"
  }'

When the contact answers, the conversation continues inside the sequence connected to subset-c673adab-2db3-4dcb-b72f-0015e1d9592c, and not at the generic opening of the flow.

• Session StartLearn how to open conversations through the Sessions endpoint.Read
• Message ProcessingUnderstand how the Chatbot Builder processes messages.Read
• NeuronsLearn what neurons are and how they work in the BotBuilder.Read