WhatsApp API Official

Overview

When using WhatsApp API Official, Session Start has a specific rule: the first outbound message cannot be an arbitrary free-form text when the conversation is not already open. To start that conversation through Talqui, your request must reference a previously approved model by sending a campaignModelID.

Even though this mechanic depends on an approved model, it is still a Session Start and not a Campaign. The operation targets one contact only, creates one session, and sends one first message as part of a transactional one-to-one flow initiated by your external system.

Request Pattern

Use the Sessions endpoint:

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": "urn:talqui:whatsapp-cloud:0",
    "pluginConnectionID": "<PLUGIN_CONNECTION_ID>",
    "contactFullName": "<CONTACT_FULL_NAME>",
    "contactExternalID": "<PHONE_NUMBER>",
    "campaignModelID": "<CAMPAIGN_MODEL_ID>",
    "messageKey": "text",
    "messageValue": "Order update notification",
    "sessionKind": "marketing",
    "campaignVariables": []
  }'

Important Fields

• channel: for this mechanic, keep the WhatsApp Official channel as urn:talqui:whatsapp-cloud:0.
• pluginConnectionID: identifies the WhatsApp Official plugin connection installed in the tenant.
• contactExternalID: the destination phone number in international format, usually 55<DDD><NUMBER> for Brazil.
• campaignModelID: identifies the approved model that Meta allows Talqui to use for the opening message.
• messageValue: works as an internal label for the operation. The actual content delivered to the user comes from the approved model referenced by campaignModelID.
• campaignVariables: fills placeholders defined in the approved model.
• sessionType and operatorID: follow the common routing rules documented in the Session Start overview.
• sessionLastSmartID: optional entry point marker for the automation layer, used when the conversation is opened as auto. The chatbot flow is the mechanic documented today, but not the only automation that accepts it. See Routing Each Model to Its Own Flow below.

Why sessionKind Is marketing

In this specific channel mechanic, Talqui opens the conversation using a Meta-approved outbound model. Because of that underlying delivery rule, the payload commonly uses sessionKind: "marketing" even when your business use case is transactional.

The important distinction is this: in Talqui, Campaigns are for sending to many contacts, while Session Start here still means opening a conversation with a single contact through the Sessions endpoint.

Routing Each Model to Its Own Flow

A tenant usually has several approved models for different subjects — an order update, a billing reminder, a delivery window. Since the model already tells the contact what the conversation is about, it rarely makes sense to answer every reply with the same generic opening menu.

When the conversation is opened as auto, the optional sessionLastSmartID field solves this. The field declares an entry point for the automation that will handle the conversation, and in the chatbot mechanic described here it carries the identifier of a sequence of the tenant's flow, so Talqui continues the conversation at that point instead of at the beginning. Sending a different identifier per model gives each model its own independent path:

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": "urn:talqui:whatsapp-cloud:0",
    "pluginConnectionID": "<PLUGIN_CONNECTION_ID>",
    "contactExternalID": "<PHONE_NUMBER>",
    "campaignModelID": "<INVOICE_DUE_MODEL_ID>",
    "messageKey": "text",
    "messageValue": "Invoice reminder",
    "sessionKind": "marketing",
    "sessionType": "auto",
    "campaignVariables": [],
    "sessionLastSmartID": "subset-c673adab-2db3-4dcb-b72f-0015e1d9592c"
  }'

The identifier is copied from the Chatbot flow in Talqui, by selecting the sequence and clicking its ⚡ action. It comes in the form subset-<uuid> and must be sent exactly as copied, with the subset- prefix. The chatbot does not speak when the model is delivered: the entry point is applied when the contact replies with a text message, and from there the conversation follows the path connected to the referenced sequence.

Response Behavior

If the request succeeds, Talqui typically returns three objects in the response:

• contact: the resolved or newly created contact.
• session: the conversation that has just been opened.
• message: the first outbound message generated from the approved model.

This response is useful when your integration needs to persist Talqui identifiers such as contactID, sessionID, or messageID for future reconciliation.