> ## Documentation Index > Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt > Use this file to discover all available pages before exploring further. # Session Start ## 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: ```bash theme={null} POST /tenants/:tenantID/sessions ``` If you still need to understand how Talqui credentials work before using this endpoint, read the [Authentication guide](/guides/introduction/authentication). ## Common Request Pattern Although each channel can apply its own rules, the common request shape is: ```bash theme={null} curl --request POST \ --url https://api.talqui.chat/tenants//sessions \ --header 'Authorization: PluginConnection ' \ --header 'content-type: application/json' \ --data '{ "channel": "", "pluginConnectionID": "", "contactExternalID": "", "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: 1. Your external system decides that it needs to contact one specific user. 2. It sends a `POST /tenants/:tenantID/sessions` request authenticated for the target plugin connection. 3. Talqui resolves or creates the contact based on the channel identity received in the payload. 4. Talqui opens the session and sends the first outbound message. 5. 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: ```json theme={null} { "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. Open a conversation using an approved model. Open a conversation with a free-form outbound message. Open an operational conversation through the iFood plugin connection. Open conversations on other channels with the generic Sessions pattern. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.