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

# Start a new conversation

> Open a conversation with one contact from your own system and send the first message, in three steps.

Use this when your system needs to reach **one contact**: an order confirmation, a delivery update, a support follow-up. Talqui finds or creates the contact, opens the conversation on the channel you choose and sends the first message. To send the same message to many contacts, use [Campaigns](https://docs.talqui.chat/guides/platform/campaigns) instead.

**1. Get an access token**

Create an [API credential](https://docs.talqui.chat/guides/introduction/authentication/api-credentials.md) in **Settings → API credentials** and exchange it for a token. Do this on your server: the secret must never reach a browser or app.

```bash theme={null}
curl -X POST https://id-api.talqui.chat/api/auth/oauth2/token \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d grant_type=client_credentials \
  -d scope=urn:talqui::::permission/all
```

The token lasts 1 hour. Reuse it until then.

**2. Find the channel connection**

A conversation always goes out through a channel connected to your workspace (a WhatsApp number, an Instagram account…). In the Talqui web app, open **Plugins**, choose the channel and open the connection: its ID is the last part of the address, after `/connections/`. You also need the channel URN, listed in [Session Start](https://docs.talqui.chat/guides/platform/sessions/session-start).

**3. Open the conversation**

> [tab] WhatsApp (official API)
>
> Outside the 24-hour service window, WhatsApp only accepts an approved model as the first message, so send its `campaignModelID`.
>
> ```bash theme={null}
> curl -X POST https://api.talqui.chat/tenants/<TENANT_ID>/sessions \
>   -H "Authorization: Bearer <ACCESS_TOKEN>" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "channel": "urn:talqui:whatsapp-cloud:0",
>     "pluginConnectionID": "<PLUGIN_CONNECTION_ID>",
>     "contactFullName": "Maria Souza",
>     "contactExternalID": "5511999990000",
>     "campaignModelID": "<CAMPAIGN_MODEL_ID>",
>     "messageKey": "text",
>     "messageValue": "Order update notification",
>     "sessionKind": "marketing",
>     "campaignVariables": []
>   }'
> ```

> [tab] Other channels
>
> Channels without that rule take a free-form first message in `messageValue`.
>
> ```bash theme={null}
> curl -X POST https://api.talqui.chat/tenants/<TENANT_ID>/sessions \
>   -H "Authorization: Bearer <ACCESS_TOKEN>" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "channel": "<CHANNEL_URN>",
>     "pluginConnectionID": "<PLUGIN_CONNECTION_ID>",
>     "contactExternalID": "<CONTACT_IDENTIFIER>",
>     "messageKey": "text",
>     "messageValue": "Hi Maria, your order has shipped.",
>     "sessionKind": "transactional",
>     "sessionType": "auto"
>   }'
> ```

`sessionType` decides who answers when the contact replies: `auto` (your automation), `queued` (the next available person) or `manual` with an `operatorID` (that operator).

The answer carries the `contact`, the `session` and the first `message`. Keep the `sessionID` if your system needs to follow the conversation.

> [!NOTE]
>
> Phone numbers go in international format, digits only: `55` + area code + number for Brazil. See [Phone number format](https://docs.talqui.chat/guides/platform/sessions/phone-number-format.md).

## Next steps

> [card] [Session Start](https://docs.talqui.chat/guides/platform/sessions/session-start)
>
> Every field, the rules of each channel and who answers the conversation.

> [card] [Manage the conversation](https://docs.talqui.chat/guides/platform/sessions/session-management.md)
>
> Assign it to an operator, transfer it to an inbox or close it through the API.


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