> ## 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.

# 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:

```bash theme={null}
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](/guides/platform/sessions/session-start).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.