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.

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.

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.