Sessions

Session Start

Updated on March 25, 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 starting point for automation flows when the session is opened as auto.
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.