Platform | Sessions

Session Start

Updated on September 11, 2026

Overview

Session Start is not the same as Campaigns. Use Campaigns when you want to send the same message, or the same approved model, to many contacts in batch or mass workflows. Use Session Start when your system needs to open a conversation with one specific contact as part of a transactional flow triggered by your application, ERP, CRM, support backend, logistics system, or marketplace integration.

When you call the Sessions endpoint to start a conversation, Talqui resolves or creates the target contact, opens a new session for that channel, and sends the first outbound message through the installed plugin connection. This makes Session Start the correct API entry point for use cases such as order confirmations, delivery updates, support follow-ups, operational alerts, or any other one-to-one conversation initiated by software.

The endpoint used for this mechanic is:

POST /tenants/:tenantID/sessions

If you still need to understand how Talqui credentials work before using this endpoint, read the Authentication guide.

Common Request Pattern

Although each channel can apply its own rules, the common request shape is:

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": "Hello from an external system",
    "sessionKind": "transactional",
    "sessionType": "auto"
  }'

The exact combination of fields may vary by channel. Some channels require campaignModelID, some expect a phone number in contactExternalID, and some use a marketplace-specific identifier instead.

Channel-Specific Mechanics

Although the endpoint is always the same, the opening rules are channel-specific:

WhatsApp API Official requires a pre-approved model (campaignModelID) to open the conversation outside the active service window.
WhatsApp Business integrations usually allow a free-form first outbound message, so the message body itself is sent in messageValue.
iFood integrations are operational and channel-constrained, so the session start is tied to the marketplace context handled by the plugin.
Other channels such as Telegram, Instagram, and Facebook Messenger follow the generic Session Start pattern, using the channel identifier plus the contact identifier expected by the installed plugin.

Common Request Flow

In most integrations, the Session Start flow is:

Your external system decides that it needs to contact one specific user.
It sends a POST /tenants/:tenantID/sessions request authenticated for the target plugin connection.
Talqui resolves or creates the contact based on the channel identity received in the payload.
Talqui opens the session and sends the first outbound message.
The response usually returns the contact, the session, and the first message created by the operation.

Contact Resolution

To identify the destination contact, Talqui accepts one of these fields:

contactID: use this when the contact already exists in Talqui and you already know its identifier.
contactExternalID: use this when you want Talqui to identify or create the contact from the channel-specific external identity.

These fields are mutually exclusive in the request. In most Session Start integrations, contactExternalID is the most common choice.

Common Payload Concepts

Most Session Start integrations use the same conceptual inputs:

channel: identifies the Talqui channel URN that should deliver the message.
pluginConnectionID: identifies which installed plugin connection will perform the send.
contactFullName: optional contact name used when Talqui needs to create or enrich the contact.
contactID: optional Talqui contact identifier used when the contact already exists.
contactExternalID: the external identifier of the contact for that channel, such as a phone number or marketplace-specific user identity.
messageKey: the type of outbound message. The Sessions endpoint accepts text, file, audio, and event, although text is the most common value for Session Start.
messageValue: the outbound content itself, or an internal label when the actual content comes from a pre-approved model.
campaignModelID: required only for mechanics that depend on an approved model, such as WhatsApp API Official.
campaignVariables: variables used to fill placeholders when the channel opens conversations through a pre-approved model.
sessionKind: classifies the business nature of the conversation. Accepted values are transactional and marketing. If omitted, Talqui uses transactional by default.
sessionType: controls how the session is routed when it is created. Accepted values are auto, queued, and manual. If omitted, Talqui uses auto by default.
operatorID: optional operator identifier used to explicitly assign the conversation to a human operator. This field is required when you want the session to start as manual.
sessionLastSmartID: optional entry point marker for the automation layer, used when the session is opened as auto. It lets your integration declare where the automation should continue, instead of always starting from its beginning. The chatbot flow is the mechanic documented today, but not the only automation that accepts it. See Automation Entry Point below.
inboxID: optional inbox identifier when your integration needs to explicitly define the target inbox.

Session Type

The sessionType field controls the initial operational state of the conversation inside Talqui:

auto: the conversation is created routed to automation. Use this when the contact should start in a bot-driven or autonomous flow.
queued: the conversation is created waiting for human handling. Use this when the conversation should enter the support queue but should not yet be assigned to a specific operator.
manual: the conversation is created already in human handling. Use this when the conversation must start directly assigned to an operator.

Operator ID

When sessionType is manual, you should also provide operatorID so Talqui knows which operator must receive the conversation on creation.

Example:

{
  "sessionType": "manual",
  "operatorID": "11111111-2222-3333-4444-555555555555"
}

If you request manual without operatorID, Talqui cannot route the conversation to a human assignee as intended. In practice, the session will not behave as a manual assignment and may fall back to queued.

Routing Notes

The final routing behavior also depends on the tenant configuration:

If sessionType is auto but the tenant does not have automation available for that flow, Talqui may fall back to queued.
If sessionType is manual but operatorID is not provided, Talqui may fall back to queued.
If sessionType is manual and operatorID is valid, the session is created already addressed to that operator.

Automation Entry Point

When a conversation is opened as auto, it is handled by the automation configured in the tenant. By default that automation starts from its own beginning, because a conversation started by the contact gives Talqui no prior context about the subject.

Session Start is different: your system already knows why it is opening the conversation — an order was delayed, an invoice is due, a delivery was rescheduled. The optional sessionLastSmartID field lets you express that, declaring the point where the automation should continue instead of starting from scratch.

sessionLastSmartID is an entry point marker for the automation layer, and not a field that belongs to a single Talqui product. The mechanic documented in this guide is the Chatbot (Flow Builder), which is the most common consumer of the field, but it is not the only automation in Talqui that can be addressed this way.

📣 Other Talqui automation mechanics also accept this marker, each with its own rules for how the value is built and interpreted. Those cases are not covered by the documentation yet. If your integration needs to target an automation other than the chatbot flow, talk to the Talqui team before assuming the behavior described below, since the expected value may follow a different pattern.

General Rules

Two rules apply regardless of which automation consumes the marker:

It is only considered when the session is opened as auto. If the tenant has no automation available for that flow, Talqui falls back to queued and the field is ignored.
It is applied only when the request actually creates a new session. If the contact already has an open conversation on the same channel and plugin connection, Talqui reuses that session and keeps its current automation position.

Chatbot Flow

When the target automation is the chatbot, the value expected by sessionLastSmartID is the identifier of a sequence of the tenant's flow. This is what allows one flow to serve many transactional scenarios, each with its own independent path.

To copy the identifier, open the Chatbot flow in Talqui, click the sequence you want to reference, and click the ⚡ action that appears on the sequence card. Talqui copies the identifier to the clipboard and confirms with the message "ID da sequência copiado para a área de transferência".

The copied value is a prefixed identifier in the form subset-<uuid>, and it must be sent exactly as copied, including the subset- prefix. The identifier is stable, so it can be stored in your application configuration:

{
  "sessionType": "auto",
  "sessionLastSmartID": "subset-c673adab-2db3-4dcb-b72f-0015e1d9592c"
}

Talqui uses the referenced sequence as an addressing marker: the conversation continues at the first block of the sequence connected to it, and the blocks inside the referenced sequence are not executed. Because of that, the recommended design is a small, empty entry sequence per scenario, connected to the path that should handle it.

Declaring the entry point also does not make the chatbot speak immediately. The first outbound message is still the one your request sends, and the entry point is applied when the contact replies with a text message.

📣 The full chatbot mechanic, including the flow layout recommended in the builder and the complete list of requirements, is documented in the Flow Entry Point guide.