Introduction
Quickstart
Authentication
REST API Reference
RTM API Reference
Campaigns
Overview
Entities
Create Campaign
Create Campaign Model
Create Campaign Dispatch
Chatbot (Flow Builder)
Overview
Message Processing
Neurons
Neuron: HTTP
Neuron: Generic
Sessions
Session Start
WhatsApp API OfficialWhatsApp BusinessiFoodGeneric Channels
Phone Number Format
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.

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.

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.
  • 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, commonly text.
  • 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.